update README.md

1 files changed, 117 insertions, 26 deletions

diff --git a/README.md b/README.md
index 9bfcd2d..8ba3034 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+# Haketilo - Make The Web Great Again!
+
 [//]: # ( SPDX-License-Identifier: CC0-1.0 )
 
 [//]: # ( Haketilo's README file )
@@ -6,39 +8,128 @@
 
 [//]: # ( Available under the terms of Creative Commons Zero v1.0 Universal. )
 
-# Haketilo - Make The Web Great Again!
+This WebExtension's goal is to allow replacing javascript served by websites with scripts specified by user. If you know NoScript or Greasemonkey, Haketilo is an extension that overlaps with functionalities and use-cases of both. It is also correct to consider it a response to a call made in RMS' ["The JavaScript Trap"](https://www.gnu.org/philosophy/javascript-trap.html).
+
+## Targetted browsers
+
+Currently we support Chromium (versions 90+, older might also work but are untested), Firefox (versions 60+) and their derivatives.
+
+## Building
+There're currently 2 ways to build Haketilo.
+
+### 1. Simple stupid way - `build.sh` script
+You only need a POSIX-compliant environment for this (shell, awk, etc.). It is a viable option if you don't need to run the automated test suite. From project's root directory, using a POSIX shell, you type either:
+``` shell
+./build.sh mozilla # to build for Firefox-based browsers
+```
+or:
+``` shell
+./build.sh chromium # to build for Chromium-based browsers
+```
+The unpacked extension shall be generated under `./mozilla-unpacked/` or `./chromium-unpacked/`, respectively. You can then load it into your browser as a temporary extension or pack it into an xpi/crx/zip archive manually, e.g.:
+``` shell
+7z a -tzip haketilo.xpi -w mozilla-unpacked/.
+```
+
+### 2. `configure`-based build
+This method assumes you have not only a POSIX environment but also a working Make tool and the zip command. From project's root directory, run the shell commands:
+``` shell
+./configure --host=mozilla # or analogically with --host=chromium
+make
+```
+This would generate the unpacked extension under `./mozilla-unpacked/` and its zipped version under `./mozilla_build.zip` (which you can rename to .xpi if you want).
+
+You can also perform an out-of-source build, for example:
+``` shell
+mkdir /tmp/haketilo-build && cd /tmp/haketilo-build
+/path/to/haketilo/sources/configure --host=chromium
+make all # will generate both ./mozilla-build.zip and ./chromium-build.zip
+```
+
+## Testing
+
+### Requirements
+
+- all that is needed for `configure`-based build
+- a Firefox-based browser (testing under Chromium is not yet supported)
+- geckodriver
+- Python3
+- Python3 bindings for Selenium
+- Python3 Pytest
+
+### Configuring
 
-This extension's goal is to allow replacing javascript served by websites
-with scripts specified by user. Something like NoScript and Greasemonkey
-together. Such facility is necessary to enable browsing World Wide Web
-without executing nonfree software.
+*Note: like building, testing can be performed out-of-source.*
 
-Currently, the target browsers for this extension are Ungoogled Chromium
-and various forks of Firefox (version 60+).
+Running tests requires you to pass some additional information to `configure`. Relevant options are:
 
-This extension is still in an early stage. Also see
-[our wiki](https://hydrillabugs.koszko.org/projects/haketilo/wiki/)
-for documentation in development.
+| **option name**  | **explanation**                                                                                                                                                                                                                                                                                                                                                                       |
+|------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `BROWSER_BINARY` | Path to the browser's binary executable. Under many scenarios the browser executable in `PATH` is a shell wrapper around the actual binary. Selenium will refuse to work with that and instead requires the binary to be passed (e.g. `/usr/lib/abrowser/abrowser` instead of `/usr/bin/abrowser`                                                                                     |
+| `CLEAN_PROFILE`  | Path to a directory with browser profile that is *"clean"*, i.e. has all extensions disabled. This is to mitigate the fact that some browsers pick up globally-installed extensions when creating a new profile for testing and these could interfere with our automated tests. This option can currently be skipped because all tests written so far run the browser in safe mode.  |
+| `DRIVER`         | Selenium driver command (e.g. `geckodriver`).                                                                                                                                                                                                                                                                                                                                         |
+| `PYTHON`         | Python 3 command. The interpreter spawned with this command is expected to have Pytest and Selenium in its import path.                                                                                                                                                                                                                                                               |
 
-## Installation
-The extension can be "built" with `./build.sh mozilla` or `./build.sh chromium`.
-This creates directories build_mozilla/ and  build_chromium/, respectively.
-Such directory can be loaded into Ungoogled Chromium or a modern Gecko-based
-browser as unpacked extension.
+Options can be specified to `configure` using the following notations (can be mixed):
+``` shell
+./configure --host=mozilla --browser-binary=/usr/local/lib/icecat/icecat
+./configure --host mozilla --browser-binary /usr/local/lib/icecat/icecat
+./configure HOST=mozilla BROWSER_BINARY=/usr/local/lib/icecat/icecat
+```
 
-## Copyright
-All copyright information is gathered in the `copyright` file which follows
-(loosely) the [format of debian/copyright file](https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/). License notices are also present in all text files of the extension.
+`configure` will try to guess the proper values for options that were not given. To help with this, you can (in some cases) give your actual browser name to `--host`, for example:
+```
+$ ./configure --host=abrowser
+Guessing SRCDIR: /home/urz/haketilo-development/browser-extension
+Guessing BROWSER_BINARY: /usr/lib/abrowser/abrowser
+Guessing DRIVER: /usr/bin/geckodriver
+Guessing PYTHON: /usr/bin/python3
+Guessing DESTDIR: /usr/share/mozilla/extensions/
+$
+```
 
-In general, this entire extension is available under the terms of GPLv3+ with
-various additional licenses and permissions for particular files.
+This may or may not work, depending on the underlying operating system and how the tools were installed.
 
-I, Wojtek Kosior, thereby promise not to sue for violation of this program's
-licenses. Although I request that you do not make use of this code in a
-proprietary program, I am not going to enforce this in court.
+### Running
+
+After configuring, the entire test suite can be run with:
+``` shell
+make test
+```
+
+Alternatively, it is possible to run Pytest directly to have some fine-grained control over which tests are run, e.g.:
+``` shell
+# Generate the necessary certificates and pytest.ini. This is done automatically
+# when running `make test`.
+make test-prepare
+
+# Optionally prevent Python from clobbering source directories with .pyc files.
+# `make test` rule does the same.
+#export PYTHONPYCACHEPREFIX="$(pwd)/test__pycache__"
+
+# Optionally stop Firefox from spawning window(s) during test.
+#export MOZ_HEADLESS=whatever
+
+# Run all popup tests with high verbosity.
+python3 -m pytest -vv -k popup
+```
+
+As of Haketilo 1.0-beta1 some tests may spuriously fail. This is the result it being notoriously difficult to avoid some weirdnesses when driving Firefox using Selenium. To make sure a failed test is not the result of some more serious bug, you might want to rerun the test suite.
+
+## Copying
+
+All copyright information is gathered in the `copyright` file which follows the [format of debian/copyright file](https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/). License notices are also present in all text files of the extension.
+
+In general, this entire extension is available under the terms of GPLv3+ with various additional licenses and permissions for particular files.
+
+I, Wojtek Kosior, thereby promise not to sue for violation of this program's licenses. Although I request that you do not make use of this code in a proprietary program, I am not going to enforce this in court.
+
+## More documentation
+
+See [our wiki](https://hydrillabugs.koszko.org/projects/haketilo/wiki/) for information.
 
 ## Contributing
-Get the code from: https://git.koszko.org/browser-extension/
-Come to: https://hydrillabugs.koszko.org/projects/haketilo
 
-Optionally, write to `$(echo a29zemtvQGtvc3prby5vcmcK | base64 -d)`
+Development happens on [our Redmine instance](https://hydrillabugs.koszko.org/projects/haketilo).
+
+Alternatively, you can write to koszko@koszko.org.