Password Manager testing automation

components/test/data/password_manager/README

Index: components/test/data/password_manager/README
diff --git a/components/test/data/password_manager/README b/components/test/data/password_manager/README
new file mode 100644
index 0000000000000000000000000000000000000000..67b6c50bd219b15b62c91bbd01a55e911cd3b90d
--- /dev/null
+++ b/components/test/data/password_manager/README
@@ -0,0 +1,171 @@
+This file contains high-level info about how to use password manager tests and 
+how to create new ones.
+
+The password manager tests purpose is to allow automatic password manager 
+checking and avoiding to do so manually.
+The tests are written in python using selenium Webdriver library.
+
+
+=====Getting started=====
+
+Build ChromeDriver by building the 'chromedriver' target. This will
+create an executable binary in the build folder named 'chromedriver[.exe]'.
+
+Build chrome too by building the 'chrome' target. This will
+create an executable binary in the build folder named 'chrome[.exe]'.
+
+Install Selenium (the version tested was 2.41.0):
+pip install -U selenium
+
+
+For security reasons, we didn't publish the passwords and the usernames we 
+used to test. So we put them to an xml file (websites.xml). The structure of 
+the file is the following:
+<websites>
+    <website name = "website name">
+        <username>username</username>
+        <password>password</password>
+    </website>
+<websites>
+You can ask someone to give you the websites.xml file and put it in the same
+folder as the tests. You can also create your own websites.xml with your
+personal accounts.
+
+Run all the working tests tests by executing:
+python tests.py --chrome-path CHROMEPATH --chromedriver-path CHROMEDRIVERPATH 
+--profile-path PROFILEPATH [--passwords_path PASSWORDSPATH]
+
+Run all the tests by executing:
+python tests.py --all --chrome-path CHROMEPATH --chromedriver-path
+CHROMEDRIVERPATH --profile-path PROFILEPATH --passwords_path PASSWORDSPATH]
+
+Run one or many tests by executing:
+python tests.py --chrome-path CHROMEPATH --chromedriver-path CHROMEDRIVERPATH 

[vabr (Chromium), 2014/05/14 15:16:09]

Is this command the same as the one for "Run all the working tests tests by
executing"?

[rchtara, 2014/05/15 09:39:11]

Done.

+--profile-path PROFILEPATH [--passwords_path PASSWORDSPATH]
+
+python tests.py google --chrome-path CHROMEPATH --chromedriver-path 
+CHROMEDRIVERPATH profile-path PROFILEPATH [--passwords_path PASSWORDSPATH]
+
+python tests.py google facebook --chrome-path CHROMEPATH --chromedriver-path 
+CHROMEDRIVERPATH --profile-path PROFILEPATH [--passwords_path PASSWORDSPATH]
+
+python tests.py google facebook amazon --chrome-path CHROMEPATH 
+--chromedriver-path CHROMEDRIVERPATH --profile-path PROFILEPATH
+[--passwords_path PASSWORDSPATH]
+
+
+=====Creating new test=====
+
+1) Open tests.py.
+
+2) Add these lines :
+website = environment.AddWebsite("website name",
+                                 "username",
+                                 "password")
+* For security reasons, you can use websites.xml which is a  private to keep 
+your passwords. You have to add the following line to the xml file:
+
+<website name = "website name">
+  <username>username</username>
+  <password>password</password>
+</website>
+
+Then, to create the new test, you need just to add:
+class NEWWEBSITE(Website):

[vabr (Chromium), 2014/05/14 15:16:09]

Using all-caps for class name is against the Python style, and should not be
present in a code example.

[rchtara, 2014/05/15 09:39:11]

Done.

+
+def Login(self):
+  self.GoTo("hhtp://url")

[vabr (Chromium), 2014/05/14 15:16:09]

hhtp->http

[rchtara, 2014/05/15 09:39:11]

Done.

+  self.FillUsername("#username")

[vabr (Chromium), 2014/05/14 15:16:09]

What do you actually mean by #username, #password?
I assume that those are CSS selectors for the elements, but it would be great to
state it explicitly (it looks like username and password values instead), and be
precise about what exactly can be used. (For example, anything from
http://www.w3schools.com/cssref/css_selectors.asp ?)

[rchtara, 2014/05/15 09:39:11]

Done.

+  self.FillPassword("#password")
+  self.Submit("#password")
+
+def Logout(self):
+  self.Click("#logout")
+
+environment.AddWebsite(
+    Yahoo("NEWWEBSITE("http://url", username_not_auto=True))

[vabr (Chromium), 2014/05/14 15:16:09]

There is an odd number (3) of quotation marks in this expression, and one more
opening parenthesis than there are closing parentheses. Did you mean to remove
'Yahoo("'?

[rchtara, 2014/05/15 09:39:11]

Done.

+
+
+3) Use the flowing methods to perform the login and logout:
+The methods that you can use are:
+* Click: find an element using CSS Selector and click on it.
+self.Click("css_selector")
+* ClickIfAvailable: find an element using CSS Selector and if it's available, 

[vabr (Chromium), 2014/05/14 15:16:09]

Please elaborate on what's the difference between Click and ClickIfAvailable.
I assume Click throws an exception if the element is not available?
Also, please specify what you mean by "available" (present in the DOM of the
page? visible?).

[rchtara, 2014/05/15 09:39:11]

Done.

+click on it.
+self.ClickIfAvailable("css_selector")
+* Enter: find an element using CSS Selector and send enter to it.
+self.Enter("css_selector")

[vabr (Chromium), 2014/05/14 15:16:09]

nit: Enter -> SendEnterTo
(The literal meaning of "enter something" seems to be too strongly competing
with the intended abbreviation. In other words, this sounds like "css_selector"
should be entered somewhere in the page.)

[rchtara, 2014/05/15 09:39:11]

Done.

+* GoTo: go to some url.

[vabr (Chromium), 2014/05/14 15:16:09]

What does "go to" mean? Navigating the main frame?

[rchtara, 2014/05/15 09:39:11]

Done.

+self.GoTo("url")
+* Hover: find an element using CSS Selector and hover it.

[vabr (Chromium), 2014/05/14 15:16:09]

hover it -> hover over it

[rchtara, 2014/05/15 09:39:11]

Done.

+self.Hover("css_selector")

[vabr (Chromium), 2014/05/14 15:16:09]

optional nit: Hover -> HoverOver

[rchtara, 2014/05/15 09:39:11]

Done.

+

[vabr (Chromium), 2014/05/14 15:16:09]

Why the blank line? Unless it separates different groups of methods, please
remove it (or put a blank line between every pair). Ditto below.

[rchtara, 2014/05/15 09:39:11]

Done.

+* IsDisplayed: check if an element is displayed.
+self.IsDisplayed("css_selector")
+* Wait: wait for some amount of time.

[vabr (Chromium), 2014/05/14 15:16:09]

Please mention units. (Seconds?)

[rchtara, 2014/05/15 09:39:11]

Done.

+self.Wait(10)
+* WaitUntilDisplayed: wait for an element defined using CSS Selector to be 
+displayed.
+self.WaitUntilDisplayed("css_selector")
+
+
+* FillPassword: find an input element using CSS Selector and fill it with

[vabr (Chromium), 2014/05/14 15:16:09]

nit: FillPasswordInto, FillUsernameInto

Just FillPassword, FillUsername hint that the password and username to be filled
are the arguments of those functions.

[rchtara, 2014/05/15 09:39:11]

Done.

+the password.
+self.FillPassword("css_selector")
+* Fillusername: find an input element using CSS Selector and fill it with
+the username.
+self.FillUsername("css_selector")
+* OptionalFillUsername: find an input element using CSS Selector and fill it 

[vabr (Chromium), 2014/05/14 15:16:09]

nit: OptionalFillUsername -> FillUsernameIfVisible

Just saying Optional does not clarify when the username is filled and when no.
(no need to add *Into, because the argument is now more tied to IfVisible)

[rchtara, 2014/05/15 09:39:11]

Done.

+with the username. Do nothing if the input element is not visible.

[vabr (Chromium), 2014/05/14 15:16:09]

Is "doing nothing" the important difference?
Or would FillUsernameInto actually throw an exception, while
FillUsernameIfVisible won't? Please clarify in the comment.

[rchtara, 2014/05/15 09:39:11]

Done.

+self.OptionalFillUsername("css_selector")
+* Submit: find an element using CSS Selector and submit it.

[vabr (Chromium), 2014/05/14 15:16:09]

optional nit: submit it -> call its submit() handler

(Again, submit X literally means taking X and putting it somewhere, whereas the
submit() method of a form means submitting the content of the form, not the form
itself. But I'm probably being language paranoid :), that's why it's just
optional. :))

[rchtara, 2014/05/15 09:39:11]

Done.

+self.Submit("css_selector")
+
+
+=====Files structure=====
+
+Classes:
+* environment.py: the definition the tests Environment.
+* website.py: Website is defined here. You need to create an instance of this 
+class for each website you want to test.
+
+Tests:
+* tests.py: the tests setup and the configuration for each website happens 
+here. This file contain 3 separate kinds of tests:
+
+1) working tests: tests that are supposed to work. If you have a problem with 
+one of them, rerun it again. Or try using the Known Issues section to fix it.
+2) tests that can cause a crash (the cause of the crash is not related to the
+password manager): This means that this set is expected to become a working 
+test or failing test when the issue that causes the crash now is solved.
+3) failing tests: tests that fail for known bug related to the password 
+manager. When this bug is solved, all the tests that were failing because of 
+it are going to be moved to working tests.
+
+Other files:
+* websites.xml : a private file where you can find all the passwords. You can 
+ask someone to give it to you or just create your own with your personal 
+accounts. 
+<websites>
+  <website name = "website name">
+    <username>username</username>
+    <password>password</password>
+  </website>
+</websites>
+
+
+=====Known Issues=====
+
+The tests are very fragile. Here are some suggestions for solving most of the 
+problems:
+* Restart the tests.
+* Remove the profile if the tests fail at the beginning for unknown reason.
+* If tests fail, isolate the one that causes problem, read the log and keep 
+your eyes on the browser window to understand its causes:
+a) In the tests, we often need to wait for a menu to appear ... If the 
+menu takes more time to appear than expected, the tests are going to fail.
+b) The websites change very often. And even if they are not changed, they some 
+time show a popup that broke the tests. In the case you need to login manually 
+to the website, close all popup and logout.
+* If you are logged in when the tests crashes, don't forget to log out before
+running the tests a second time.