Issue 132 - Add REAMDE to adblockplustests repository

README.md

Index: README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..8501c610915a2d163f11172f114de972ec286705
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# Adblock Plus Tests
+
+## Introduction
+
+The `adblockplustests` repository contains the test suite for the Adblock Plus
+Firefox extension `adblockplus`. This test suite is itself a separate Firefox

[Wladimir Palant, 2015/10/09 17:35:01]

"for the Adblock Plus Firefox extension `adblockplus`" => "for the Adblock Plus
extension in Firefox"

[kzar, 2015/10/12 11:06:07]

Done.

+extension which interacts with the Adblock Plus extension in order to test it.
+(It is therefore assumed that the tests should pass when the latest available
+revisions of `adblockplus` and `adblockplustests` are used in combination.)
+
+Some of the tests in this test suite are also re-used by the Chrome/Opera/Safari
+version of Adblock Plus `adblockpluschrome`. They are included in the
+repository as a dependency, and they are run from within the extension using its
+in-built test runner. (The dependency is managed by the `ensure_dependencies.py`
+script and the expected revision of `adblockplustests` is therefore specified
+explicitly.)

[Wladimir Palant, 2015/10/09 17:35:01]

Please don't document technical details, these can change. I'd replace this
paragraph by the following:

Some of the tests in this test suite are also reused by the Chrome/Opera/Safari
version of Adblock Plus. Please see the `adblockpluschrome` repository for
details on how to run the tests there.

[kzar, 2015/10/12 11:06:08]

Done.

+
+
+## Usage
+
+### Firefox
+
+To test your changes to Adblock Plus for Firefox you will need to build and
+install both your modified version of the extension and the test suite. For
+each project you will need to type the following:
+
+    ./build.py build
+
+This will create a build with a name in the form
+`adblockplus[tests]-1.2.3.nnnn.xpi`, which you can then manually add to Firefox.
+
+Alternatively, to speed up the process, you can install the
+[Extension Auto-Installer](https://addons.mozilla.org/addon/autoinstaller)
+extension. Assuming that Extension Auto-Installer is configured to use port 8888
+(the default value), you can build and install in one step by running:
+
+    ./build.py autoinstall 8888
+
+Once both the Adblock Plus and Adblock Plus Tests extensions have been built and
+installed you can run the test suite by opening the Firefox Add-ons Manager,
+pressing the "Preferences" button for the Adblock Plus Tests extension and then
+pressing the "Run" button.
+
+Things to note:
+
+- The test suite can take some time to run, sometimes several minutes.
+- If you re-install the Adblock Plus Tests extension you will need to re-load
+  the preferences page before pressing "Run" again. Otherwise the tests will not
+  re-start.
+- The final storage tests often get stuck.
+- Some tests will fail intermittently with a `NS_ERROR_FAILURE` message.
+- Several `Content policy: HTML embed (Java)` tests are currently failing.

[Wladimir Palant, 2015/10/09 17:35:01]

I'd not document specific test failures, these can get out of date very quickly.
Instead:

- Some tests are currently known to fail (sometimes depending on your browser
version and configuration). It is better to test this before making any changes.

[kzar, 2015/10/12 11:06:08]

Done.

+
+
+### Chrome

[Sebastian Noack, 2015/10/09 12:00:09]

IMO this section is irrelevant and redundant here.

[kzar, 2015/10/09 14:39:42]

Yea, maybe you're right. I wasn't sure either way on this one.

My reason for wanting to include _something_ about it was that I did not realise
that Adblock Plus for Chrome used any of these tests initially. I found it a
little surprising. (I'm pretty sure I pushed changed to this repository without
first checking the Chrome tests still passed before I realised this.)

[Wladimir Palant, 2015/10/09 17:35:01]

I agree with Sebastian, this is unnecessary. The note above and the reference to
adblockpluschrome repository are sufficient.

[kzar, 2015/10/12 11:06:07]

Done.

+
+To test your changes to Adblock Plus for Chrome, go to the extension's options
+page, open the JavaScript Console and type:
+
+    location.href = "qunit/index.html";
+
+The unit tests should then run automatically in the page. For more information
+about building and testing the Chrome extension please refer to [the project's
+README file](https://hg.adblockplus.org/adblockpluschrome/file/tip/README.md).