Skip to content

Commit

Permalink
Add links to the testing frameworks
Browse files Browse the repository at this point in the history
  • Loading branch information
Jaifroid committed Aug 10, 2023
1 parent 1253889 commit 91fdc4d
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 8 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ _You must test your code yourself before asking for review, like this_:
identified, see [TESTS](./TESTS.md) so you can debug;
* End-to-end (e2e) tests are also run on GitHub Actions when you push to your PR. These test typical user actions in a headless browser. Tests are currently enabled for latest
Firefox, Edge, Chrome in Linux and Windows, and in IE Mode on Windows (this is the equivalent to testing on Internet Explorer 11). You can run these tests yourself in a
non-headless browser with `npm run tests-e2e-firefox`, `npm run tests-e2e-iemode`, etc. For more information, see [TESTS.md](./TESTS.md).
non-headless browser with `npm run tests-e2e-firefox`, `npm run tests-e2e-iemode`, etc. For more information, see [TESTS](./TESTS.md).
* As an alternative to the Vite server, we also provide [http-server](https://www.npmjs.com/package/http-server), which you can launch by running `npm run web-server` in the root of
this repository. This does not have Hot Module Replacement, and you will need to refresh the page yourself by doing `Ctrl-Shift-R` with DevTools open. Again, you will only see the
latest version of your code if you turn on "Bypass AppCache" and turn off the browser's native caching (see above).
Expand Down
18 changes: 11 additions & 7 deletions TESTS.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,28 @@
# Automated tests

[For information about manual tests we expect contributors to undertake before requesting a review, please see [Contributing -> Testing](./CONTRIBUTING.md#testing).
The information below is about the automated testing that is undertaken. You will need this information if an automated test fails, so that you can debug the failure
by running the automated tests locally.]

We run two types of automated tests on each push and pull request. These are Unit tests and End-to-end (e2e) tests. Unit tests are designed to test small units of code, crucial
functions that the rest of the app relies on. End-to-end tests are designed to test the functionality of the app as it might be used by a typical user.

## Unit tests

Unit tests are implemented, for historic reaons, with QUnit. When run in an automated way, these are currently run by using the browser testing framework Test_Café.
Unit tests are implemented, for historic reaons, with QUnit. When run in an automated way, these are currently run by using the browser testing framework TestCafé.

You can manually run and debug Unit tests simply by opening `tests/index.html` in Firefox, Edge, or Chromium/Chrome through a (local) web server, such as Vite or http-server (see
[CONTRIBUTING](./CONTRIBUTING.md)). Use DevTools (F12) to debug and find out what is failing. Note that this only tests the unbundled
(source) code, and so it only works in browsers that support ES6 modules. You *cannot* use these tests in IE11 or older Firefox/Chromium.

You can run the unit tests with npm on all your installed browsers with `npm test` in your terminal. Before running the tests, if you didn't already, you will need to fetch
You can run the Unit tests with npm on all your installed browsers with `npm test` in your terminal. Before running the tests, if you didn't already, you will need to fetch
development dependencies (see "[Build system and setup](./CONTRIBUTING.md#build-system-and-setup)"). If testing this way,
make sure that `http-server` is not already running, because another copy is launched for these tests, and the ports may conflict. If running tests in parallel like this produces
unexpected results (some tests might be too slow and assert before they have completed correctly), then you can run individual tests in headless mode with
`npm run test-unit-firefox`, `npm run test-unit-edge`, etc. (see `package.json` for full list of scripts). Note that browsers need to be available in standard locations for this
to work: they won't be fetched or installed by the script.

We currently use [TestCafé](https://testcafe.io/) to run the unit tests in headless browsers in GitHub actions. If you want to run this locally, you can find out which browsers it
We currently use [TestCafé](https://testcafe.io/) to run the Unit tests in headless browsers in GitHub actions. If you want to run this locally, you can find out which browsers it
knows about by running `npx testcafe --list-browsers` (it may take some time to discover local browsers).

When you run `npm test`, it will run the tests visually, not headless. The individual browser tests (e.g. `npm run test-unit-chrome`) are run headless. If you want to run these
Expand All @@ -27,10 +31,10 @@ commandline, then you'll need, e.g., `npx testcafe chrome ./tests/initTestCafe.j

## End-to-end tests

End-to-end (e2e) tests are implemented with Selenium WebDriver, which in turn uses Mocha as the testing framework. The tests can be found in the `tests` directory, and are
implemented as ES6 modules. Each test consists of a runner for a specified browser (e.g. `microsoftEdge.e2e.runner.js`) which in turn imports one or more specification test suites
(e.g. `legacy-ray_charles.e2e.spec.js`). The test suites load a specific ZIM archive, and undertake tests in both JQuery and ServiceWorker modes. Each ZIM tested should have its own
`e2e.spec.js` suite.
End-to-end (e2e) tests are implemented with [Selenium WebDriver](https://www.selenium.dev/documentation/webdriver/), which in turn uses [Mocha](https://mochajs.org/) as the testing
framework. The tests can be found in the `tests` directory, and are implemented as ES6 modules. Each test consists of a runner for a specified browser (e.g.
`microsoftEdge.e2e.runner.js`) which in turn imports one or more specification test suites (e.g. `legacy-ray_charles.e2e.spec.js`). The test suites load a specific ZIM archive,
and undertake tests in both JQuery and ServiceWorker modes. Each ZIM tested should have its own `e2e.spec.js` suite.

These tests are run automatically on every push and pull request by the GitHub Actions runner `CI.yml` (in the `.github/workflows` directory). They can also be run locally with the
following procedure:
Expand Down

0 comments on commit 91fdc4d

Please sign in to comment.