Lancelot Graphics Testing: Difference between revisions
No edit summary |
(→The QPainter Lancelot test: fix incorrect path) |
||
| (5 intermediate revisions by 3 users not shown) | |||
| Line 3: | Line 3: | ||
The Lancelot system is an extension of the [http://doc.qt.io/qt-5/qtest.html 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. | The Lancelot system is an extension of the [http://doc.qt.io/qt-5/qtest.html 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! ==== | ====Not all mismatches are regressions!==== | ||
The Lancelot 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. | The Lancelot 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 is an [https://testresults.qt.io/lancebot/LanceBot6/tst_Quick3D/auto-reports/ | For illustration, here is an [https://testresults.qt.io/lancebot/LanceBot6/tst_Quick3D/auto-reports/Report_Feb02-212344.html example report]. | ||
There are currently three Lancelot-based tests in Qt, in qtbase, qtdeclarative, and | There are currently three Lancelot-based tests in Qt, in qtbase, qtdeclarative, and qtquick3d; described below. | ||
The Lancelot 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. | The Lancelot 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: the early warning system=== | ||
The LanceBot may run a before-after comparison on a gerrit change. If given gerrit change (or chain), the bot will run the corresponding lancelot test two times. First, the repo at the change's parent SHA will be compiled and used to generate the lancelot baselines. Then, the SHA including the gerrit change will be compiled, and a comparison lancelot run is performed. | |||
If a mismatch is detected, the bot posts a comment to the gerrit change. The comment contains a link to the Lancelot report, so the commit author and reviewers can inspect the rendering differences caused by the patch set. In contrast to the Sanity Bot, 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. | If a mismatch is detected, the bot posts a comment to the gerrit change. The comment contains a link to the Lancelot report, so the commit author and reviewers can inspect the rendering differences caused by the patch set. In contrast to the Sanity Bot, 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. | ||
| Line 19: | Line 19: | ||
It may be noted that LanceBot does not post any +1 votes when no mismatches is detected either.Since that is the case for the vast majority of gerrit changes, such votes would be spam. | It may be noted that LanceBot does not post any +1 votes when no mismatches is detected either.Since that is the case for the vast majority of gerrit changes, such votes would be spam. | ||
==== False LanceBot reports ==== | ====False LanceBot reports==== | ||
Long experience has shown that false reports are pretty rare. However you may on occasion experience situations like the following: | Long experience has shown that false reports are pretty rare. However you may on occasion experience situations like the following: | ||
==== Contact ==== | *''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 maintainer on [mailto:eirik.aavitsland@qt.io email]. | For questions, contact the maintainer on [mailto:eirik.aavitsland@qt.io email]. | ||
== The Lancelot tests == | ==The Lancelot tests== | ||
=== The QPainter Lancelot test === | ===The QPainter Lancelot test=== | ||
Path: ''qtbase/tests/ | Path: ''qtbase/tests/baseline'' | ||
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. | 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. | ||
| Line 38: | Line 39: | ||
To render a test scene locally, use the lance tool. Example: | To render a test scene locally, use the lance tool. Example: | ||
<code>./qtbase/tests/manual/lance/lance -i qtbase/tests/ | <code>./qtbase/tests/manual/lance/lance -i qtbase/tests/baseline/painting/scripts/aliasing.qps</code> | ||
=== The Qt Quick Lancelot test === | ===The Qt Quick Lancelot test=== | ||
Path: ''qtdeclarative/tests/manual/scenegraph_lancelot'' | Path: ''qtdeclarative/tests/manual/scenegraph_lancelot'' | ||
| Line 49: | Line 50: | ||
To render a scene locally, simply use the qmlscene tool. Example: | To render a scene locally, simply use the qmlscene tool. Example: | ||
<code>/myqtdir/bin/qmlscene qtdeclarative/tests/ | <code>/myqtdir/bin/qmlscene qtdeclarative/tests/baseline/scenegraph/data/borderimages/borderimage.qml</code> | ||
One can also use the qmlscenegrabber tool, see below. | |||
=== The Qt Quick3D Lancelot test === | ===The Qt Quick3D Lancelot test=== | ||
Path: ''qtquick3d/tests/auto/quick3d_lancelot'' | Path: ''qtquick3d/tests/auto/quick3d_lancelot'' | ||
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. | 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. | LanceBot normally runs this test once with each of the RHI backends supported by the host machine. | ||
To render a scene locally, | To render a scene locally, use the qmlscenegrabber tool that is built as part of the test. Example, for only viewing: | ||
<code>mytestbuilddir/bin_dir/qmlscenegrabber -viewonly qtquick3d/tests/auto/quick3d_lancelot/data/camera/DefaultCamera.qml</code> | |||
To test the grabbing locally, do for example: | |||
<code>mytestbuilddir/bin_dir/qmlscenegrabber -o out.png qtquick3d/tests/auto/quick3d_lancelot/data/camera/DefaultCamera.qml</code> | |||
That will store the scene grab in ''foo.png''. | |||
===Repos=== | |||
* https://code.qt.io/cgit/qt/qtqa.git/tree/scripts/lancebot lancelot test-run driver | |||
* https://code.qt.io/cgit/qt/qtbase.git/tree/tests/baseline/shared lancelot server | |||
* https://code.qt.io/cgit/qt/qtbase.git/tree/tests/baseline/painting/scripts lancelot 2D painting tests | |||
Latest revision as of 22:14, 17 April 2024
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 Lancelot 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 is an example report.
There are currently three Lancelot-based tests in Qt, in qtbase, qtdeclarative, and qtquick3d; described below.
The Lancelot 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
The LanceBot may run a before-after comparison on a gerrit change. If given gerrit change (or chain), the bot will run the corresponding lancelot test two times. First, the repo at the change's parent SHA will be compiled and used to generate the lancelot baselines. Then, the SHA including the gerrit change will be compiled, and a comparison lancelot run is performed.
If a mismatch is detected, the bot posts a comment to the gerrit change. The comment contains a link to the Lancelot report, so the commit author and reviewers can inspect the rendering differences caused by the patch set. In contrast to the Sanity Bot, 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.
It may be noted that LanceBot does not post any +1 votes when no mismatches is detected either.Since that is the case for the vast majority of gerrit changes, such votes would be spam.
False LanceBot reports
Long experience has shown that false reports are pretty rare. However you 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 maintainer on email.
The Lancelot tests
The QPainter Lancelot test
Path: qtbase/tests/baseline
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 Lancelot test
Path: qtdeclarative/tests/manual/scenegraph_lancelot
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 5.x, that means OpenGL and the 2D rendering backend (QT_QUICK_BACKEND=software). For Qt 6.x, it means the supported RHI backends, plus software rendering.
To render a scene locally, simply use the qmlscene tool. Example:
/myqtdir/bin/qmlscene qtdeclarative/tests/baseline/scenegraph/data/borderimages/borderimage.qml
One can also use the qmlscenegrabber tool, see below.
The Qt Quick3D Lancelot test
Path: qtquick3d/tests/auto/quick3d_lancelot
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 qmlscenegrabber tool that is built as part of the test. Example, for only viewing:
mytestbuilddir/bin_dir/qmlscenegrabber -viewonly qtquick3d/tests/auto/quick3d_lancelot/data/camera/DefaultCamera.qml
To test the grabbing locally, do for example:
mytestbuilddir/bin_dir/qmlscenegrabber -o out.png qtquick3d/tests/auto/quick3d_lancelot/data/camera/DefaultCamera.qml
That will store the scene grab in foo.png.
Repos
- https://code.qt.io/cgit/qt/qtqa.git/tree/scripts/lancebot lancelot test-run driver
- https://code.qt.io/cgit/qt/qtbase.git/tree/tests/baseline/shared lancelot server
- https://code.qt.io/cgit/qt/qtbase.git/tree/tests/baseline/painting/scripts lancelot 2D painting tests