Lancelot Graphics Testing
The Baseline graphics testing sytem (traditionally, the "Lancelot" system) is an extension of the QTest unit test framework. Its purpose is to help catch regressions in Qt's graphics rendering. It facilitates rendering a suite of test scenes, and comparing the produced output images with the images produced from a previous rendering run. When mismatches are detected, a simple web-based report is generated. The report shows the produced "before" and "after" images, and highlights the differences.
Not all mismatches are regressions!
The Baseline test system was created on the realization that rendering output is not suited for normal unit testing. The reason is simply that a hard-coded, automated test can not decide if a rendering difference is an improvement or a regression. Hence, such a test would reject a bug-fixing code change just as a bug-introducing code change. Hence, manual inspection of the mismatches is needed to make the decision.
For illustration, here are the latest reports for commits to the SVG module.
There are a number of Baseline tests in Qt. By convention, they are placed in the <code>tests/baseline</code> directory in the module's source repo.
The Baseline system is designed around a networked Baseline server, where the produced images are stored for usage as comparison on later runs. The Baseline server also creates and serves the mismatch reports.
LanceBot: the early warning system
LanceBot is designed to run a before-and-after comparison ("A-B test") on a specific gerrit commit. When the bot is triggered (by a gerrit comment) on a certain commit (or chain of commits) to test, the bot will run the module's default Baseline test 2 times:
- First, the repo at the change's parent SHA will be compiled and the test will be run to generate baseline images.
- Then, the SHA including the gerrit change will be compiled, and a comparison run is performed. In this way, any rendering changes introduced by the commit will be detected.
If a mismatch is detected, LanceBot posts a comment to the gerrit commit. The comment contains a link to the Baseline test report, so the commit author and reviewers can inspect the rendering differences caused by the patch set.
In contrast to other bots, LanceBot does not give any -1 votes, since it cannot judge if the mismatch is benign or not. Naturally, reviewers are not expected to approve a commit that causes unacceptable rendering regressions.
False LanceBot reports
Long experience has shown that false reports are pretty rare. However one may on occasion experience situations like the following:
- Your code does not touch graphics at all, but still mismatches are shown. This may happen if you do changes to e.g. the qml engine. It means your code causes general regressions, and would probably fail in the CI, and they hit on the lancelot test scenes too.
- A LanceBot comment is posted, but it lacks a report link or other relevant information. This is caused by a problem in the LanceBot system itself; please contact the maintainer (see below).
Contact
For questions, contact the Oslo Graphics Team on Teams chat (Qt Company internal), or the maintainer on email.
Details about some of the Baseline tests
The QPainter Baseline test
Path: <code>qtbase/tests/baseline/painting</code>
This test exercises Qt's 2D graphics engine. The test scenes are specified in Qt Painting Script (QPS), a simple special-purpose script language. QPS scripts map directly over to QPainter API calls.
The test has a number of test functions. Each function paints the suite of test scenes with different color depths/pixel format, in order to try out different painting code paths. Also, two of the functions use the OpenGL paint engine.
To render a test scene locally, use the lance tool. Example:
./qtbase/tests/manual/lance/lance -i qtbase/tests/baseline/painting/scripts/aliasing.qps
The Qt Quick Baseline test
Path: <code>qtdeclarative/tests/baseline/scenegraph</code>
This test exercises the Quick scene graph rendering. The test scenes are specified as normal qml scripts. For obvious reasons, the scenes must be non-interactive and static.
For best coverage, LanceBot will normally run this test once for each supported graphics stack on the test host machine. For Qt 6.x, that means the supported RHI backends, plus software rendering.
To render a scene locally, simply use the qml tool. Example:
/myqtdir/bin/qml qtdeclarative/tests/baseline/scenegraph/data/borderimages/borderimage.qml
One can also use the qmlscenegrabber tool that is built as part of the test, ref. below.
The Qt Quick3D Baseline test
Path: <code>qtquick3d/tests/baseline</code>
This test exercises the Quick3D rendering. The test scenes are specified as normal qml scripts. For obvious reasons, the scenes must be non-interactive and static - i.e. animation, if any, must freeze within a few seconds so that a deterministic window grab can be taken.
LanceBot normally runs this test once with each of the RHI backends supported by the host machine.
To render a scene locally, use the qquick3d_qmlscenegrabber tool that is built as part of the test. Example, for only viewing:
qquick3d_scenegrabber -viewonly qtquick3d/tests/auto/quick3d_lancelot/data/camera/DefaultCamera.qml
To test the grabbing locally, do for example:
qquick3d_/qmlscenegrabber -o out.png qtquick3d/tests/auto/quick3d_lancelot/data/camera/DefaultCamera.qml
That will store the scene grab in foo.png.