diff --git a/docs/tests-ui.rst b/docs/tests-ui.rst index 5c771e47e42..24d62a5702a 100644 --- a/docs/tests-ui.rst +++ b/docs/tests-ui.rst @@ -1,51 +1,89 @@ Client-side Testing with Intern =============================== -The client-side testing tool for the MDN front-end is `Intern `_, a Selenium WebDriver API which allows developers to write automated testing via JavaScript. Intern is an open source project created and maintained by `SitePen `_. +We use `Intern `_ for client-side testing. It uses Selenium WebDriver API which lets us write automated testing via JavaScript. Intern is an open source project created and maintained by `SitePen `_. Installing Dependencies ----------------------- -1. Install `JDK `_ +1. Go to the ``tests/ui/`` directory:: -2. Download the most current release of Selenium `WebDriver `_. Download the current standalone version which is a `.jar` file. + cd tests/ui -3. From the `tests/ui/` directory, use NPM or another package manager to install Intern:: +2. Use ``npm`` to install Intern:: npm install intern@^3.0 -Do *not* install Intern globally -- path issues may occur. - -Firefox appears to work out of the box, but `Chrome `_ and `Safari `_ drivers must be downloaded and installed separately. +.. warning:: Do *not* install Intern globally -- path issues may occur. Running Tests ------------- -1. From the command line, start WebDriver:: +On your machine +~~~~~~~~~~~~~~~ + +1. Install `JDK `_ + +2. Download the most current `release of Selenium `_ standalone server. (It's the ``.jar`` file.) + +.. note:: Firefox should work out of the box. You need to install `Chrome `_ and `Safari `_ drivers yourself. + +3. From the command line, start WebDriver:: # Substitute your WebDriver version in the `#` chars java -jar /path/to/selenium-server-standalone-#.#.#.jar -2. From within the `tests/ui/` directory, run intern on your local intern config file (omitting the `.js`):: +4. Go to the ``tests/ui/`` directory:: - node_modules/.bin/intern-runner config=intern-local + cd tests/ui -The above runs the entire suite of tests. Custom functionality has been added to allow for command line arguments to be passed to modify configuration, namely: +5. Run intern with the ``intern-local`` config file (omit the ``.js``):: -* `b` to set which browsers to run in (ex: `b=chrome,firefox`) - omit and all browsers will run -* `t` for which test suites to run (ex: `t=wiki,home`) - omit and all tests will run -* `u` to provide a username for Persona -* `p` to provide a password for Persona -* `d` for which domain to run on (ex: `developer.allizom.org`) -* `destructive=true` to signal real docs can be created (do not run this on production) -* `wd` which represents the slug of an existing article to test (ex: `My_Test_Doc`) + ./node_modules/.bin/intern-runner config=intern-local b=firefox -An example:: +The above tries to run the entire suite of tests. You can change the behavior with `command line arguments`_. E.g., :: node_modules/.bin/intern-runner config=intern-local b=firefox,chrome t=auth,homepage d=developer-local.allizom.org u=someone@somewhere.com p=8675309 wd='Web' destructive=true The user credentials must be Persona-only (not GMail or Mozilla LDAP lookups). User credentials are the only required custom command line arguments. +On a Cloud Provider +~~~~~~~~~~~~~~~~~~~ + +We have tested running the Intern test suite with BrowserStack and SauceLabs. +We have better luck with BrowserStack, and it's the provider MDN staff devs +use. + +1. Sign up for either `BrowserStack `_ or `SauceLabs `_. + +2. Go to the ``tests/ui/`` directory:: + + cd tests/ui + +3. Set the `appropriate environment variables + `_ with your provider credentials. + E.g., :: + + export BROWSERSTACK_USERNAME='fakeuser' + export BROWSERSTACK_ACCESS_KEY='fakeaccesskey' + +3. Run intern with the appropriate config file (omitting the ``.js``). E.g., :: + + ./node_modules/.bin/intern-runner config=intern-browserstack + +.. _command line arguments: + +Command-Line Arguments +~~~~~~~~~~~~~~~~~~~~~~ + +* ``b`` - browsers to run (e.g., ``b=chrome,firefox``) +* ``t`` - test suites to run (e.g., ``t=wiki,homepage``) +* ``d`` - domain to run against (e.g., ``d=developer.allizom.org``) +* ``u`` - username for Persona (e.g., ``u=testuser@example.com``) +* ``p`` - password for Persona (e.g., ``p=testpass``) +* ``wd`` - slug of existing article to test (e.g., ``wd=My_Test_Doc``) +* ``destructive=true`` - create real docs (do not run this on production) + Adding a Test Suite -------------------