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 def Logout(self): 79 # Add logout steps for the website, for example: 80 self.Click("Logout button CSS selector") 81 82 Then, to create the new test, you need just to add: 83 84 environment.AddWebsiteTest(NewWebsiteTest("website name")) 85 86 * For security reasons, passwords and usernames need to be supplied in a 87 separate XML file and never checked in to the repository. The XML file should 88 contain data structured like this: 89 90 <website name = "website name"> 91 <username>username</username> 92 <password>password</password> 93 </website> 94 95 The "website name" is only used to find the username and password in the xml 96 file. 97 98 99 Use the flowing methods to perform the login and logout: 100 The methods that you can use are: 101 102 * Click: find an element using CSS Selector and click on it. Throw an 103 exception if the element is not visible. 104 self.Click("css_selector") 105 * ClickIfClickable: find an element using CSS Selector and click on it if it's 106 possible to do that. 107 self.ClickIfClickable("css_selector") 108 * GoTo: navigate the main frame to a url. 109 self.GoTo("url") 110 * HoverOver: find an element using CSS Selector and hover over it. 111 self.HoverOver("css_selector") 112 * SendEnterTo: find an element using CSS Selector and send enter to it. 113 self.SendEnterTo("css_selector") 114 115 * IsDisplayed: check if an element is displayed. 116 self.IsDisplayed("css_selector") 117 * Wait: wait for some amount of time in seconds. 118 self.Wait(10) 119 * WaitUntilDisplayed: wait for an element defined using CSS Selector to be 120 displayed. 121 self.WaitUntilDisplayed("css_selector") 122 123 * FillPasswordInto: find an input element using CSS Selector and fill it with 124 the password. 125 self.FillPasswordInto("css_selector") 126 * FillUsernameInto: find an input element using CSS Selector and fill it with 127 the username. 128 self.FillUsernameInto("css_selector") 129 * Submit: find an element using CSS Selector and call its submit() handler. 130 self.Submit("css_selector") 131 132 133 =====Files structure===== 134 135 Classes: 136 * environment.py: the definition the tests Environment. 137 * websitetest.py: WebsiteTest is defined here. You need to create an instance 138 of this class for each website you want to test. 139 140 Tests: 141 * tests.py: the tests setup and the configuration for each website happens 142 here. This file contain 3 separate kinds of tests: 143 144 1) working tests: tests that are supposed to work. If you have a problem with 145 one of them, rerun it again. Or try using the Known Issues section to fix it. 146 2) tests that can cause a crash (the cause of the crash is not related to the 147 password manager): This means that this set is expected to become a working 148 test or failing test when the issue that causes the crash now is solved. 149 3) failing tests: tests that fail for known bug related to the password 150 manager. When this bug is solved, all the tests that were failing because of 151 it are going to be moved to working tests. 152 153 Other files: 154 * websites.xml : a private file where you can find all the passwords. You can 155 ask someone to give it to you or just create your own with your personal 156 accounts. 157 <websites> 158 <website name = "website name"> 159 <username>username</username> 160 <password>password</password> 161 </website> 162 </websites> 163 164 165 =====Known Issues===== 166 167 The tests are very fragile. Here are some suggestions for solving most of the 168 problems: 169 * Restart the tests. 170 * Remove the profile if the tests fail at the beginning for unknown reason. 171 * If tests fail, isolate the one that causes problem, read debugging messages 172 and keep your eyes on the browser window to understand its causes: 173 a) In the tests, we often need to wait for a menu to appear ... If the 174 menu takes more time to appear than expected, the tests are going to fail. 175 b) The websites change very often. And even if they are not changed, they some 176 time show a popup that broke the tests. In the case you need to login manually 177 to the website, close all popup and logout. 178 * If you are logged in when the tests crashes, don't forget to log out before 179 running the tests a second time. 180
