Automated Testing

WissKI includes several automated tests to ensure that WissKI functionality remains intact. phpunit is used to implement and run these automated tests. They are configured using phpunit.xml.dist, which also configures various required environment variables.

They can be run inside the devcontainer using phpunit .. They are run on CI using the PHPUnit job.

CI PHPUnit configuration

GitLab Templates concurrent PHPUnit uses Drupal core's run-tests.sh, which does not use phpunit.xml.dist as-is (it defaults to core's config, and the relative paths in the devcontainer file break when that file is passed through from the CI project root).

On the phpunit job, misc/tests/generate-phpunit-ci-xml.php copies phpunit.xml.dist to a gitignored phpunit-ci.xml.dist and adjusts it for CI. Then CI uses drupal/core's run-tests.sh is pointed at the generated file via _RUNTESTS_EXTRA.

Edit only phpunit.xml.dist; do not commit phpunit-ci.xml.dist.

Overview & Infrastructure

All tests are located inside the wisski_core/tests folder. Despite being in the wisski_core module folder, they test all WissKI modules. This choice condenses all test code into a single source location.

The tests specifically make use of a real triplestore. They also require a controllable HTTP server that is reachable from the testing environment. The tests expect the following two components:

1. An RDF4J Instance to dynamically create triplestore repositories on demand. We make use of the RD4J Rest API to create transient in-memory triplestores.
2. A web server to serve static files. This is a custom go server, that supports placing files using the PUT and DELETE methods. It's source code can be found at github.com/FAU-CDI/static_test_server). All data is transient, and only held in memory.

Both are configured using environment variables inside the phpunit configuration file. By default, RDF4J is expected to run on http://rdf4j:8080/rdf4j-server/ and the static webserver is expected to be reachable at http://static:8888. There should be no need to re-configure these, as both are available automatically both in CI and the devcontainer.

Running Tests in the devcontainer

To run the tests locally in the devcontainer you have two choices:

• Use the phpunit binary directly: This will run each test sequentially. It also takes several arguments to limit which tests should be run, for example to run just a single test: phpunit ./wisski_core/tests/src/Functional/Sanity/PoFilesTest.php
• Use the misc/scripts/run_tests.sh script wrapper. This script uses drupal/core's run_tests.sh script to run tests concurrently (8 by default). The wrapper is needed to adjust several wisski-specific settings, use the --help argument for more details.

Test Structure & the wisski_test module

The tests split into two categories: - Functional Tests. - Functional JavaScript Tests

These live in the Functional and FunctionalJavascript directories, respectively. For testing purposes the wisski_test module exists. It contains utility code needed for supporting the tests.

Functional tests parts of WissKI which do not require any JavaScript to run. Functional Javascript tests may test functions that require JavaScript. At minimum, this is anything that requires Ajax. Functional Javascript tests are a lot slower to run that functional tests, therefore new tests should prefer not to require JavaScript.

Tests extend their corresponding base classes:

• \Drupal\wisski_test\WisskiFunctionalTestBase for functional tests; and
• \Drupal\wisski_test\WisskiJavascriptTestBase for functional javascript tests.

These each setup a blank Drupal for testing, enabling all WissKI and related modules, and perform additional setup.

Test groups

Directories reflect test type (Functional / FunctionalJavascript / Unit). PHPUnit #[Group] attributes reflect functionality. All real WissKI tests carry the wisski group. Product tests add one or more functional groups from the table below. Harness tests under wisski_test carry the meta.

Group	Meaning
wisski	Anything testing WissKI itself as opposed to infrastructure.
sanity	Smoke checks: modules, routes, services
salz	SALZ adapter CRUD, queries, endpoints
entity	Entity behaviour: save, publish state, URI resolver, form serialization
storage	Loading/persistence internals: original values, serialization, load context, revisions
permissions	Access control on view/list routes
views	Views rendering and display integration
query	Entity query API
pathbuilder	Pathbuilder UI and import/generation workflow
ontology	Ontology load and reasoning
triplestore	Triplestore write verification on entity create
settings	Admin settings and bundle title-pattern UI
meta	Tests of wisski_test helpers: traits, services, RDF4J/static infrastructure

To run a specific group:

phpunit --group permissions .

--group accepts any name from the table; phpunit --group wisski . runs the full suite.

New product tests should include wisski plus at least one functional group (it might also make sense to add a new group). New harness tests in wisski_test/test should include only meta.

Writing your own Tests

(to be documented; for now some hints)

• use autocomplete in the test classes to determine available methods.
• to produce a screenshot inside of a functional javascript test, use $this->createScreenshot($filename);. At the end of a test run, the created screenshots will be logged to the console.
• to produce additional text output, use TextLogger::log($some_text). It will be dumped to the console at the end of the test.
• Use methods of ErrorLogTrait to debug error messages - especially when debugging ajax failures.

Debugging tests

A specific helper trait ensures that it is also possible to debug the tests inside the devcontainer. Specifically, the XDEBUG_TRIGGER environment variable is automatically forwarded to any running test code.

It is therefore possible to trigger XDEBUG with something like:

XDEBUG_TRIGGER=1 phpunit .