Haketilo

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¶

• 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¶

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:

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

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.