From c2024f1e63ec8558df24996273d8d79070614df5 Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 9 Nov 2015 21:35:10 -0500 Subject: [PATCH] minor corrections to usage documentation: new command to generate MANIFEST.json, use paths for meta and tests that are more consistent with conventions, and update "path" to "manifest:default" for the default ini file. --- docs/usage.rst | 42 ++++++++++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 279f4f2c590419..8e74a4320c8287 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -28,19 +28,19 @@ environment created as above:: pip install -e ./ In addition to the dependencies installed by pip, wptrunner requires -a copy of the web-platform-tests repository. That can be located -anywhere on the filesystem, but the easiest option is to put it within -the wptrunner checkout directory, as a subdirectory named ``tests``:: +a copy of the web-platform-tests repository. This can be located +anywhere on the filesystem, but the easiest option is to put it +under the same parent directory as the wptrunner checkout:: - git clone https://github.com/w3c/web-platform-tests.git tests + git clone https://github.com/w3c/web-platform-tests.git It is also necessary to generate a web-platform-tests ``MANIFEST.json`` -file. It's recommended to put that within the wptrunner -checkout directory, in a subdirectory named ``meta``:: +file. It's recommended to also put that under the same parent directory as +the wptrunner checkout, in a directory named ``meta``:: mkdir meta - cd tests - python tools/scripts/manifest.py ../meta/MANIFEST.json + cd web-platform-tests + python manifest --path ../meta/MANIFEST.json The ``MANIFEST.json`` file needs to be regenerated each time the web-platform-tests checkout is updated. To aid with the update process @@ -74,6 +74,9 @@ takes multiple options, of which the following are most significant: ``--prefs-root`` (required only when testing a Firefox binary) The path to a directory containing Firefox test-harness preferences. [#]_ +``--config`` (should default to `wptrunner.default.ini`) + The path to the config (ini) file. + .. [#] The ``--certutil-binary`` option is required when the product is ``firefox`` unless ``--ssl-type=none`` is specified. @@ -94,10 +97,17 @@ The following examples show how to start wptrunner with various options. Starting wptrunner ------------------ +The examples below assume the following directory layout, +though no specific folder structure is required:: + + ~/testtwf/wptrunner # wptrunner checkout + ~/testtwf/web-platform-tests # web-platform-tests checkout + ~/testtwf/meta # metadata + To test a Firefox Nightly build in an OS X environment, you might start wptrunner using something similar to the following example:: - wptrunner --metadata=~/web-platform-tests/ --tests=~/web-platform-tests/ \ + wptrunner --metadata=~/testtwf/meta/ --tests=~/testtwf/web-platform-tests/ \ --binary=~/mozilla-central/obj-x86_64-apple-darwin14.3.0/dist/Nightly.app/Contents/MacOS/firefox \ --certutil-binary=~/mozilla-central/obj-x86_64-apple-darwin14.3.0/security/nss/cmd/certutil/certutil \ --prefs-root=~/mozilla-central/testing/profiles @@ -106,7 +116,7 @@ wptrunner using something similar to the following example:: And to test a Chromium build in an OS X environment, you might start wptrunner using something similar to the following example:: - wptrunner --metadata=~/web-platform-tests/ --tests=~/web-platform-tests/ \ + wptrunner --metadata=~/testtwf/meta/ --tests=~/testtwf/web-platform-tests/ \ --binary=~/chromium/src/out/Release/Chromium.app/Contents/MacOS/Chromium \ --webdriver-binary=/usr/local/bin/chromedriver --product=chrome @@ -118,7 +128,7 @@ To restrict a test run just to tests in a particular web-platform-tests subdirectory, specify the directory name in the positional arguments after the options; for example, run just the tests in the `dom` subdirectory:: - wptrunner --metadata=~/web-platform-tests/ --tests=~/web-platform-tests/ \ + wptrunner --metadata=~/testtwf/meta --tests=~/testtwf/web-platform-tests/ \ --binary=/path/to/firefox --certutil-binary=/path/to/certutil \ --prefs-root=/path/to/testing/profiles \ dom @@ -180,7 +190,7 @@ Configuration File wptrunner uses a ``.ini`` file to control some configuration sections. The file has three sections; ``[products]``, -``[paths]`` and ``[web-platform-tests]``. +``[manifest:default]`` and ``[web-platform-tests]``. ``[products]`` is used to define the set of available products. By default this section is empty @@ -195,12 +205,12 @@ e.g.:: chrome = netscape4 = path/to/netscape.py -``[paths]`` specifies the default paths for the tests and metadata, +``[manifest:default]`` specifies the default paths for the tests and metadata, relative to the config file. For example:: - [paths] - tests = checkouts/web-platform-tests - metadata = /home/example/wpt/metadata + [manifest:default] + tests = ~/testtwf/web-platform-tests + metadata = ~/testtwf/meta ``[web-platform-tests]`` is used to set the properties of the upstream