|
1
|
# Haketilo - Make The Web Great Again!
|
|
2
|
|
|
3
|
[//]: # ( SPDX-License-Identifier: CC0-1.0 )
|
|
4
|
|
|
5
|
[//]: # ( Haketilo's README file )
|
|
6
|
|
|
7
|
[//]: # ( Copyright (C) 2021 Wojtek Kosior )
|
|
8
|
|
|
9
|
[//]: # ( Available under the terms of Creative Commons Zero v1.0 Universal. )
|
|
10
|
|
|
11
|
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).
|
|
12
|
|
|
13
|
## Targetted browsers
|
|
14
|
|
|
15
|
Currently we support Chromium (versions 90+, older might also work but are untested), Firefox (versions 60+) and their derivatives.
|
|
16
|
|
|
17
|
## Building
|
|
18
|
There're currently 2 ways to build Haketilo.
|
|
19
|
|
|
20
|
### 1. Simple stupid way - `build.sh` script
|
|
21
|
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:
|
|
22
|
``` shell
|
|
23
|
./build.sh mozilla # to build for Firefox-based browsers
|
|
24
|
```
|
|
25
|
or:
|
|
26
|
``` shell
|
|
27
|
./build.sh chromium # to build for Chromium-based browsers
|
|
28
|
```
|
|
29
|
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.:
|
|
30
|
``` shell
|
|
31
|
7z a -tzip haketilo.xpi -w mozilla-unpacked/.
|
|
32
|
```
|
|
33
|
|
|
34
|
### 2. `configure`-based build
|
|
35
|
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:
|
|
36
|
``` shell
|
|
37
|
./configure --host=mozilla # or analogically with --host=chromium
|
|
38
|
make
|
|
39
|
```
|
|
40
|
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).
|
|
41
|
|
|
42
|
You can also perform an out-of-source build, for example:
|
|
43
|
``` shell
|
|
44
|
mkdir /tmp/haketilo-build && cd /tmp/haketilo-build
|
|
45
|
/path/to/haketilo/sources/configure --host=chromium
|
|
46
|
make all # will generate both ./mozilla-build.zip and ./chromium-build.zip
|
|
47
|
```
|
|
48
|
|
|
49
|
## Testing
|
|
50
|
|
|
51
|
### Requirements
|
|
52
|
|
|
53
|
- all that is needed for `configure`-based build
|
|
54
|
- a Firefox-based browser (testing under Chromium is not yet supported)
|
|
55
|
- geckodriver
|
|
56
|
- Python3
|
|
57
|
- Python3 bindings for Selenium
|
|
58
|
- Python3 Pytest
|
|
59
|
|
|
60
|
### Configuring
|
|
61
|
|
|
62
|
*Note: like building, testing can be performed out-of-source; this can be useful when testing under multiple browsers simultaneously*
|
|
63
|
|
|
64
|
Running tests requires you to pass some additional information to `configure`. Relevant options are:
|
|
65
|
|
|
66
|
| **option name** | **explanation** |
|
|
67
|
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
68
|
| `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` |
|
|
69
|
| `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. |
|
|
70
|
| `DRIVER` | Selenium driver command (e.g. `geckodriver`). |
|
|
71
|
| `PYTHON` | Python 3 command. The interpreter spawned with this command is expected to have Pytest and Selenium in its import path. |
|
|
72
|
|
|
73
|
Options can be specified to `configure` using the following notations (can be mixed):
|
|
74
|
``` shell
|
|
75
|
./configure --host=mozilla --browser-binary=/usr/local/lib/icecat/icecat
|
|
76
|
./configure --host mozilla --browser-binary /usr/local/lib/icecat/icecat
|
|
77
|
./configure HOST=mozilla BROWSER_BINARY=/usr/local/lib/icecat/icecat
|
|
78
|
```
|
|
79
|
|
|
80
|
`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:
|
|
81
|
```
|
|
82
|
$ ./configure --host=abrowser
|
|
83
|
Guessing SRCDIR: /home/urz/haketilo-development/browser-extension
|
|
84
|
Guessing BROWSER_BINARY: /usr/lib/abrowser/abrowser
|
|
85
|
Guessing DRIVER: /usr/bin/geckodriver
|
|
86
|
Guessing PYTHON: /usr/bin/python3
|
|
87
|
Guessing DESTDIR: /usr/share/mozilla/extensions/
|
|
88
|
$
|
|
89
|
```
|
|
90
|
|
|
91
|
This may or may not work, depending on the underlying operating system and how the tools were installed.
|
|
92
|
|
|
93
|
### Running
|
|
94
|
|
|
95
|
After configuring, the entire test suite can be run with:
|
|
96
|
``` shell
|
|
97
|
make test
|
|
98
|
```
|
|
99
|
|
|
100
|
Alternatively, it is possible to run Pytest directly to have some fine-grained control over which tests are run, e.g.:
|
|
101
|
``` shell
|
|
102
|
# Generate the necessary certificates and pytest.ini. This is done automatically
|
|
103
|
# when running `make test`.
|
|
104
|
make test-prepare
|
|
105
|
|
|
106
|
# Optionally prevent Python from clobbering source directories with .pyc files.
|
|
107
|
# `make test` rule does the same.
|
|
108
|
#export PYTHONPYCACHEPREFIX="$(pwd)/test__pycache__"
|
|
109
|
|
|
110
|
# Optionally stop Firefox from spawning window(s) during test.
|
|
111
|
#export MOZ_HEADLESS=whatever
|
|
112
|
|
|
113
|
# Run all popup tests with high verbosity.
|
|
114
|
python3 -m pytest -vv -k popup
|
|
115
|
```
|
|
116
|
|
|
117
|
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.
|
|
118
|
|
|
119
|
### Setting up an environment for manual testing
|
|
120
|
|
|
121
|
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:
|
|
122
|
``` python
|
|
123
|
from time import sleep
|
|
124
|
sleep(100000)
|
|
125
|
```
|
|
126
|
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.
|
|
127
|
|
|
128
|
## Copying
|
|
129
|
|
|
130
|
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.
|
|
131
|
|
|
132
|
In general, this entire extension is available under the terms of GPLv3+ with various additional licenses and permissions for particular files.
|
|
133
|
|
|
134
|
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.
|
|
135
|
|
|
136
|
## More documentation
|
|
137
|
|
|
138
|
See [our wiki](https://hydrillabugs.koszko.org/projects/haketilo/wiki/) for information.
|
|
139
|
|
|
140
|
## Contributing
|
|
141
|
|
|
142
|
Development happens on [our Redmine instance](https://hydrillabugs.koszko.org/projects/haketilo).
|
|
143
|
|
|
144
|
Alternatively, you can write to koszko@koszko.org.
|