privatebin/unit-testing repository overview

⁠PrivateBin unit testing container image

PrivateBin is a minimalist, open source online pastebin⁠ where the server has zero knowledge of pasted data. Data is encrypted and decrypted in the browser using 256bit AES in Galois Counter mode⁠.

This repository contains the Dockerfile and resources needed to create a container image with a pre-installed phpunit & mocha, as well as the JavaScript tooling of PrivateBin. The image is based on the alpine image, extended with PHP 8.5 (including the GD and SQLite modules), the Google Cloud Storage library & the nodejs LTS release. Run the container with your local PrivateBin repository as a read-only volume and it will run both the PHP and JavaScript test suites in parallel and return the results.

⁠Running the image

Assuming you have docker (or podman) successfully installed and internet access, you can fetch and run the image from either the docker hub⁠ or the GitHub container registry⁠ like this:

docker run --rm --read-only -v ~/PrivateBin:/srv:ro --tmpfs /tmp privatebin/unit-testing
docker run --rm --read-only -v ~/PrivateBin:/srv:ro --tmpfs /tmp ghcr.io/privatebin/unit-testing

The examples below use the docker hub image, but the GitHub container registry one can be used interchangeably.

The parameters in detail:

• -v ~/PrivateBin:/srv:ro - Replace ~/PrivateBin with the location of the checked out PrivateBin repository on your machine. It is recommended to mount it read-only, which guarantees that your repository isn't damaged by an accidentally destructive test case in it.
• --read-only - This image supports running in read-only mode. Only /tmp may be written into.
• --tmpfs /tmp - Provides the writable /tmp as an in-memory filesystem.
• --rm - Remove the container after the run. This saves you doing a cleanup on your docker environment, if you run the image frequently.

Note: Inside the container, the first thing that will be done is to copy your repository into /tmp/repo. The unit tests are then run in this copy. While this slows things down a bit, it ensures that a test script inside your repository can't accidentally delete objects in it.

The container exits with a non-zero status if any of the test suites failed.

⁠Running just phpunit or mocha

Optionally you can run just the PHP or JavaScript unit tests by specifying the optional parameter:

docker run --rm --read-only -v ~/PrivateBin:/srv:ro --tmpfs /tmp privatebin/unit-testing phpunit
docker run --rm --read-only -v ~/PrivateBin:/srv:ro --tmpfs /tmp privatebin/unit-testing mocha

You may also limit the test execution to a single test file to speed up repeats:

docker run --rm --read-only -v ~/PrivateBin:/srv:ro --tmpfs /tmp privatebin/unit-testing phpunit ConfigurationTest.php
docker run --rm --read-only -v ~/PrivateBin:/srv:ro --tmpfs /tmp privatebin/unit-testing mocha test/Helper.js

⁠Running other JavaScript tools

Any other tool installed from PrivateBin's js/package.json can be run as well, i.e. eslint, jshint or nyc. These get executed in the js folder of the repository copy:

docker run --rm --read-only -v ~/PrivateBin:/srv:ro --tmpfs /tmp privatebin/unit-testing eslint .
docker run --rm --read-only -v ~/PrivateBin:/srv:ro --tmpfs /tmp privatebin/unit-testing jshint privatebin.js legacy.js
docker run --rm --read-only -v ~/PrivateBin:/srv:ro --tmpfs /tmp privatebin/unit-testing nyc mocha

⁠Rolling your own image

The image installs the npm and composer modules required by PrivateBin, so building it requires a checkout of the PrivateBin repository, passed in as the named build context privatebin. This requires podman 4.2 or later, or docker with buildx. To reproduce the image, run:

docker build --build-context privatebin=../PrivateBin -t privatebin/unit-testing .

The included Makefile builds the image and runs the tests using podman, logging the output of each step into the log folder. The container engine, image name and location of the PrivateBin repository can be overridden:

make all
make test ENGINE=docker PRIVATEBIN=~/PrivateBin
make help

The image is built using the dependencies of the current PrivateBin master branch and verified against it on every push & pull request, as well as weekly, to pick up dependency updates of PrivateBin. On master, a successfully verified image is then published as latest to both the docker hub and the GitHub container registry, for amd64 & arm64.

⁠Behind the scenes

Since both unit test frameworks process the test cases linearly, both use only one CPU core. Nowadays most systems have more than one, so the entrypoint script launches mocha in the background and phpunit in the foreground. On systems with 2 or more CPUs they can therefore run in parallel. Since mocha usually takes longer, its output gets displayed after phpunit.

The npm modules get installed exactly as locked in PrivateBin's js/package-lock.json. For composer, the development requirements of PrivateBin's composer.json (i.e. phpunit) get installed, along with the latest compatible Google Cloud Storage library, as done in PrivateBin's own CI.