Browse files

Merge pull request #99 from sashakruglov/readme

  • Loading branch information...
2 parents c679117 + eab7268 commit 23f21c37ebb1b307a43e2e8a7f0a1323281ad800 @AlinT AlinT committed Mar 18, 2013
Showing with 105 additions and 44 deletions.
  1. +105 −44
@@ -1,74 +1,134 @@
-MozTrap Tests
+Selenium Tests for (MozTrap)
-Automated tests for the MozTrap web application.
-The following contributors have submitted pull requests to moztrap-tests:
+Thank you for checking out Mozilla's MozTrap test suite. Mozilla and the [Web QA][webqa] team are grateful for the help and hard work of many contributors like yourself.
+The following contributors have submitted pull requests to MozTrap-Tests:
-Running Tests
+Getting involved as a contributor
+We love working with contributors to fill out the Selenium test coverage for MozTrap-Tests, but it does require a few skills. You will need to know some Python, some Selenium and you will need some basic familiarity with Github.
+If you know some Python, it's worth having a look at the Selenium framework to understand the basic concepts of browser based testing and especially page objects. Our suite uses [Selenium WebDriver][webdriver].
+If you need to brush up on programming but are eager to start contributing immediately, please consider helping us find bugs in Mozilla [Firefox][firefox] or find bugs in the Mozilla web-sites tested by the [Web QA][webqa] team.
+To brush up on Python skills before engaging with us, [Dive Into Python][dive] is an excellent resource. MIT also has [lecture notes on Python][mit] available through their open courseware.The programming concepts you will need to know include functions, working with classes, and some object oriented programming basics.
+Questions are always welcome
+While we take pains to keep our documentation updated, the best source of information is those of us who work on the project. Don't be afraid to join us in [#mozwebqa][mozwebqa] to ask questions about our Selenium tests. Mozilla also hosts the [#mozillians][mozillians] chat room to answer your general questions about contributing to Mozilla.
+How to Set up and Build MozTrap Tests Locally
+This repository contains Selenium tests used to test the website
+Mozilla maintains a guide to running Automated tests on our QMO website:
+This wiki page has some advanced instructions specific to Windows:
-### Java
-You will need a version of the [Java Runtime Environment][JRE] installed
+###You will need to install the following:
-### Python
-Before you will be able to run these tests you will need to have Python 2.6 installed.
+#### Git
+If you have cloned this project already then you can skip this!
+GitHub has excellent guides for [Windows][GitWin], [MacOSX][GitMacOSX] and [Linux][GitLinux].
-The below instructions will install the required Python libraries into your
-global Python installation. If you work on multiple Python projects that might
-end up needing different versions of the same libraries, you might want to
-follow `sudo easy_install pip` with `sudo pip install virtualenv`, and then
-create and activate a [virtualenv]( (e.g. `virtualenv
-moztrap-tests-env; source moztrap-tests-env/bin/activate`) to
-create a clean "virtual environment" for just this project. Then you can `pip
-install -r requiremenst/mozwebqa.txt` in your virtual environment without
-needing to use `sudo`.
+#### Python
+Before you will be able to run these tests you will need to have [Python 2.6][Python2.6] or [Python 2.7][Python2.7] installed.
-If you don't mind installing globally, just run
+Install pip (for managing Python packages):
sudo easy_install pip
-followed by
- sudo pip install -r requirements/mozwebqa.txt
+ sudo apt-get install python-pip
+####Virtualenv and Virtualenvwrapper (Optional/Intermediate level)
+While most of us have had some experience using virtual machines, [virtualenv][venv] is something else entirely. It's used to keep libraries that you install from clashing and messing up your local environment. After installing virtualenv, installing [virtualenvwrapper][wrapper] will give you some nice commands to use with virtualenvwrapper.
-If you are running on Ubuntu/Debian you will need to first do
- sudo apt-get install python-setuptools
+#### Installing dependencies
-to install the required Python libraries.
+If you are using virtualenv, create and activate the virtualenv, then run the following in the project root:
-### Selenium
-Once this is all set up you will need to download and start a Selenium server. You can download the latest Selenium server from [here][Selenium Downloads]. The filename will be something like 'selenium-server-standalone-2.5.0.jar'
+ pip install -r requirements.txt
-To start the Selenium server run the following command:
+If you are not using virtualenv, run the following in the project root to install dependencies globally:
- java -jar ~/Downloads/selenium-server-standalone-2.5.0.jar
+ sudo pip install -r requirements.txt
-Change the path/name to the downloaded Selenium server file.
+####Initializing git submodules
+Be sure to retrieve the git submodules by issuing this command at the project root:
-[Selenium Downloads]:
+ git submodule update --init
+#### Running tests locally
+Tests are run using the py.test library. You will find examples here for running all of the tests, tests in one file and running a single test.
+WebDriver does not need a Selenium Server or Grid to run so these examples bypass this step and just use the --driver command.
+An example of running all tests without a Selenium Server:
+ py.test --driver=firefox --credentials=/path/to/credentials/credentials.yaml --destructive .
-### Running tests locally
+An example of running all of the tests in one file:
-To run tests locally it's a simple case of calling py.test from the
-moztrap-tests directory. You should specify the following argument for
-Selenium RC: --api=rc
+ py.test --driver=firefox --credentials=/path/to/credentials/credentials.yaml tests/
-The base URL should be a valid instance of MozTrap: the staging env is
+An example of running one test in a file:
- py.test --api=rc --baseurl=
+ py.test --driver=firefox --credentials=/path/to/credentials/credentials.yaml tests/ -k test_that_user_can_create_and_delete_run
-For other possible options, type py.test --help .
+The mozwebqa plugin has advanced command line options for reporting and using browsers. See the documentation on [davehunt's pytest mozwebqa github][pymozwebqa].
+#### Moz-grid-config (Optional/Intermediate level)
+Prerequisites: [Java Runtime Environment][Java JRE], [Apache Ant][ANT]
+[Moz-grid-config][moz-grid] is a project containining our Selenium Grid configuration. It uses Apache Ant to run the Selenium hub or node to the configuration defined in the yaml files.
+We recommend git cloning the repository for a couple of reasons:
+1. The commands to launch a node or hub are all pre-configured and as simple as typing `ant launch-hub` or `ant launch-node`
+2. The paths to browser binaries and nodes can be stored in configuration (yaml) files
+3. It contains a jar file of the latest Selenium in it's lib directory
+(If you prefer to download Selenium it's own, you can do that from [here][Selenium Downloads])
+You will need to make sure that the name of your Firefox application matches one of the names in moz-grid-config/grid_configuration.yml. As an example: even though Firefox typically installs without a version number in the name, moz-grid-config requires it to be named "Firefox <version number>".app on mac.
+[Java JRE]:
+[Selenium Downloads]:
Writing Tests
@@ -79,7 +139,8 @@ we'd like to ask you to do:
1. Use the [template files][GitHub Templates] for all new tests and page objects
2. Follow our simple [style guide][Style Guide]
3. Fork this project with your own GitHub account
-4. Make sure all tests are passing, and submit a pull request with your changes
+4. Add your test into the "tests" folder and the necessary methods for it into the appropriate file in "pages"
+5. Make sure all tests are passing and submit a pull request with your changes
[GitHub Templates]:
[Style Guide]:
@@ -92,4 +153,4 @@ This software is licensed under the [MPL] 2.0:
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at

0 comments on commit 23f21c3

Please sign in to comment.