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:

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

*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):

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

```

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

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

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

``` python

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.