Launch Testing

The automatic tests run on pushes and pull requests now also includes launch testing - this is an automated script that checks that it is possible to launch the game and start a new save. This was originally added in the #299 PR.

"My commits fail this test and I don't know why!"

Your code seems to prevent the game from launching - try running the code on your local machine to see if it also does work there. You can view the last 30 lines of the logs of a failed run by clicking on 'details' next to the failed test. If it does not appear that there is an Exception raised, please ensure commit c91c5ed is in your branch - previously, the test's failure conditions were mistakenly inverted.

Texture loading problems can sometimes be attributed to incorrect capitalisation - Windows and MacOS are case insensitive for historical reasons, but Linux (which this test uses) and other nix-like operating systems generally use case sensitive file systems. Furthermore, the test fails on any Exception encountered when launching the game - non-existent textures which are referenced throw exceptions, but do not crash the game until it attempts to render it.

If you believe there is an error in the test, please use the #launch-test-discussion channel.

How to use

General Usecase

Simply push to your branch. This will run automatically through GitHub Actions and provide feedback in the same place as unit tests.

Running Locally

There should not be much need to run the test locally - all it does is launch through gradle and start a new game. However, if you wish to run it locally, the commands Xvfb, xdotool and xwd need to be available - on Debian and related distributions, you can install these through sudo apt install xvfb xdotool x11-apps.

Running locally (as opposed to github actions) has the benefit that the full game logs are stored - these can be found in game.log.

Verifying that the test has run successfully

This should not be necessary, but can be done. This is Click the test results and then select 'details':

Go to the summary tab (on the left), scroll down to artifacts and download the game-screenshot zip file.

Extracting the zip file will reveal a game-launched.xwd file. This can be opened in an image viewer or editor (such as GIMP) to view and to ensure that the game has launched correctly.

Script breakdown

The test can be summarised as such:

1. Creating a virtual X Framebuffer - essentially this is an Xorg server that uses a chunk of memory as a framebuffer instead of a display output. This virtual screen is 1280x1024, with 8-bit colour depth.
2. Launching the game through gradle, storing the stdout as gradle.log and the stderr (where the game outputs its logs) to game.log
3. Wait 35 seconds for gradle to build and launch the game
4. Move mouse to position (640, 417) and click for 'new game'
5. Wait 10 seconds to ensure the UI has updated to the intro animation
6. Move mouse position to (640,790) and click for 'continue'
7. Wait 12s for crash animation to play.
8. Move mouse position to (640,512) and click for 'awaken'
9. Wait 35 seconds for world to load.
10. Take a screenshot of the entire (virtual) screen.
11. Kill gradle, the game, Xvfb and any other spawned processes.
12. Check if the string 'Exception' has shown up in the game.log file - if it has, print out the last 30 lines exit with a non-zero exit code.