aboutsummaryrefslogtreecommitdiff
;; This is a Guix channel.

(channel
  (version 0)
  (news-file "etc/news.scm")
  (keyring-reference "keyring")
  (url "https://git.savannah.gnu.org/git/guix.git")) ;the primary URL
generated by cgit

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".

Targeted 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:

./build.sh mozilla # to build for Firefox-based browsers

or:

./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.:

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:

./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:

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

Configuring

Note: like building, testing can be performed out-of-source; this can be useful when testing under multiple browsers simultaneously

Running tests requires you to pass some additional information to configure. Relevant options are:

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.

Options can be specified to configure using the following notations (can be mixed):

./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

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/
$

This may or may not work, depending on the underlying operating system and how the tools were installed.

Running

After configuring, the entire test suite can be run with:

make test

Alternatively, it is possible to run Pytest directly to have some fine-grained control over which tests are run, e.g.:

# 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 2.0 some tests may spuriously fail. This is the result of 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.

Setting up an environment for manual testing

The automated tests are run with browser's all network requests going through a Python proxy. The proxy allows us to mock websites that are then navigated to in the browser. At times you might want to replicate this test environment while playing manually with the browser. A poor man's approach is to add something like:

from time import sleep
sleep(100000)

inside one of the test functions and then run that test function from Pytest (with MOZ_HEADLESS unset!). This might make sense when debugging some particular test case. For general experiments we have instead provided convenience targets make test-environment and make test-environment-with-haketilo. Running any of those will spawn a browser window together with a Python shell where driver variable will hold Selenium driver object controlling that browser. In case of the test-environment-with-haketilo target the browser will additionally appear with Haketilo loaded into it.

Copying

All copyright information is gathered in the copyright file which follows the format of debian/copyright file. 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 for information.

Contributing

Development happens on our Redmine instance.

Alternatively, you can write to koszko@koszko.org.