components/test/data/password_manager/automated_tests/README

   1 This file contains high-level info about how to use password manager tests and
   2 how to create new ones.
   3
   4 The password manager tests purpose is to allow automatic password manager
   5 checking and avoiding to do so manually.
   6 The tests are written in python using selenium Webdriver library.
   7
   8
   9 =====Getting started=====
  10
  11 Build ChromeDriver by building the 'chromedriver' target. This will
  12 create an executable binary in the build folder named 'chromedriver[.exe]'.
  13
  14 Build chrome too by building the 'chrome' target. This will
  15 create an executable binary in the build folder named 'chrome[.exe]'.
  16
  17 Install Selenium (the version tested was 2.41.0):
  18 pip install -U selenium
  19
  20
  21 For security reasons, we didn't publish the passwords and the usernames we
  22 used to test. So we put them to an xml file (websites.xml). The structure of
  23 the file is the following:
  24 <websites>
  25     <website name = "website name">
  26         <username>username</username>
  27         <password>password</password>
  28     </website>
  29 <websites>
  30 You can ask someone to give you the websites.xml file and put it in the same
  31 folder as the tests. You can also create your own websites.xml with your
  32 personal accounts.
  33 WARNING: All the content of the PROFILEPATH is going to be deleted.
  34 Show the help:
  35 python tests.py --help
  36 Run all the working tests tests by executing:
  37 python tests.py --chrome-path CHROMEPATH --chromedriver-path CHROMEDRIVERPATH
  38 --profile-path PROFILEPATH [--passwords_path PASSWORDSPATH]
  39
  40 Run all the tests by executing:
  41 python tests.py --all --chrome-path CHROMEPATH --chromedriver-path
  42 CHROMEDRIVERPATH --profile-path PROFILEPATH [--passwords_path PASSWORDSPATH]
  43
  44 Run one or many tests by executing:
  45 python tests.py google --chrome-path CHROMEPATH --chromedriver-path
  46 CHROMEDRIVERPATH profile-path PROFILEPATH [--passwords_path PASSWORDSPATH]
  47
  48 python tests.py google facebook --chrome-path CHROMEPATH --chromedriver-path
  49 CHROMEDRIVERPATH --profile-path PROFILEPATH [--passwords_path PASSWORDSPATH]
  50
  51 python tests.py google facebook amazon --chrome-path CHROMEPATH
  52 --chromedriver-path CHROMEDRIVERPATH --profile-path PROFILEPATH
  53 [--passwords_path PASSWORDSPATH]
  54
  55 To display the debugging messages on the screen, use:
  56 python tests.py --log DEBUG|INFO|WARNING|ERROR|CRITICAL --log-screen
  57 To save debugging messages into a file, use:
  58 python tests.py --log DEBUG|INFO|WARNING|ERROR|CRITICAL --log-file LOG_FILE
  59
  60 To save the result of the tests as an xml file, use:
  61 python tests.py --save-path SAVERESULTPATH
  62
  63 =====Creating new test=====
  64
  65 1) Open tests.py.
  66
  67 2) Add tests like this:
  68
  69 class NewWebsiteTest(WebsiteTest):
  70
  71   def Login(self):
  72     # Add login steps for the website, for example:
  73     self.GoTo("http://url")
  74     self.FillUsernameInto("Username CSS selector")
  75     self.FillPasswordInto("Password CSS selector")
  76     self.Submit("Password CSS selector")
  77
  78 Then, to create the new test, you need just to add:
  79
  80 environment.AddWebsiteTest(NewWebsiteTest("website name"))
  81
  82 * For security reasons, passwords and usernames need to be supplied in a
  83 separate XML file and never checked in to the repository. The XML file should
  84 contain data structured like this:
  85
  86 <website name = "website name">
  87   <username>username</username>
  88   <password>password</password>
  89 </website>
  90
  91 The "website name" is only used to find the username and password in the xml
  92 file.
  93
  94
  95 Use the flowing methods to perform the login and logout:
  96 The methods that you can use are:
  97
  98 * Click: find an element using CSS Selector and click on it. Throw an
  99 exception if the element is not visible.
 100 self.Click("css_selector")
 101 * ClickIfClickable: find an element using CSS Selector and click on it if it's
 102 possible to do that.
 103 self.ClickIfClickable("css_selector")
 104 * GoTo: navigate the main frame to a url.
 105 self.GoTo("url")
 106 * HoverOver: find an element using CSS Selector and hover over it.
 107 self.HoverOver("css_selector")
 108
 109 * IsDisplayed: check if an element is displayed.
 110 self.IsDisplayed("css_selector")
 111 * Wait: wait for some amount of time in seconds.
 112 self.Wait(10)
 113 * WaitUntilDisplayed: wait for an element defined using CSS Selector to be
 114 displayed.
 115 self.WaitUntilDisplayed("css_selector")
 116
 117 * FillPasswordInto: find an input element using CSS Selector and fill it with
 118 the password.
 119 self.FillPasswordInto("css_selector")
 120 * FillUsernameInto: find an input element using CSS Selector and fill it with
 121 the username.
 122 self.FillUsernameInto("css_selector")
 123 * Submit: find an element using CSS Selector and call its submit() handler.
 124 self.Submit("css_selector")
 125
 126
 127 =====Files structure=====
 128
 129 Classes:
 130 * environment.py: the definition the tests Environment.
 131 * websitetest.py: WebsiteTest is defined here. You need to create an instance
 132 of this class for each website you want to test.
 133
 134 Tests:
 135 * tests.py: the tests setup and the configuration for each website happens
 136 here. This file contain 3 separate kinds of tests:
 137
 138 1) working tests: tests that are supposed to work. If you have a problem with
 139 one of them, rerun it again. Or try using the Known Issues section to fix it.
 140 2) tests that can cause a crash (the cause of the crash is not related to the
 141 password manager): This means that this set is expected to become a working
 142 test or failing test when the issue that causes the crash now is solved.
 143 3) failing tests: tests that fail for known bug related to the password
 144 manager. When this bug is solved, all the tests that were failing because of
 145 it are going to be moved to working tests.
 146
 147 Other files:
 148 * websites.xml: a private file where you can find all the passwords. You can
 149 ask someone to give it to you or just create your own with your personal
 150 accounts.
 151 <websites>
 152   <website name = "website name">
 153     <username>username</username>
 154     <password>password</password>
 155   </website>
 156 </websites>
 157
 158
 159 =====Known Issues=====
 160
 161 The tests are very fragile. Here are some suggestions for solving most of the
 162 problems:
 163 * Restart the tests.
 164 * Remove the profile if the tests fail at the beginning for unknown reason.
 165 * If tests fail, isolate the one that causes problem, read debugging messages
 166 and keep your eyes on the browser window to understand its causes:
 167 a) In the tests, we often need to wait for a menu to appear ... If the
 168 menu takes more time to appear than expected, the tests are going to fail.
 169 b) The websites change very often. And even if they are not changed, they some
 170 time show a popup that broke the tests. In the case you need to login manually
 171 to the website, close all popup and logout.
 172 * If you are logged in when the tests crashes, don't forget to log out before
 173 running the tests a second time.