This document describes both filing issues and contributing pull requests to
QmlWeb.
First of all, build QmlWeb from the master branch and ensure that the problem
is observable there. If it is not — just wait for the next QmlWeb release.
A snapshot of master branch could also be downloaded from GitHub as an
archive.
Building requires Node.js with npm, and is done by
executing npm install && npm run build.
If the problem is still observable — continue according to the categories below.
Also take a minute to consider if that issue is already filed, if it is — don't file a duplicate 😉. If you didn't find an issue identical to yours or not sure — it will be fine even if it will turn out to be a duplicate, though.
Don't submit issues of this kind as-is. Do either one of the following:
- Break it down to a problem with a single QML element, then see Elements issues.
- Break it down to a minimal testcase where all used Elements are supported but QmlWeb engine malfunctions. See Core/Engine issues.
- See Questions for everything else. We can help with that, but GitHub issues is just not the right channel for that.
Before filing an issue, check out the Projects page and find that specific element to ensure that it is already implemented.
Please, do not file issues for individual unsupported elements (where the implementation is not «Ready to use» yet), or elements where only a stub implementation exists. Instead, consider writing a stub implementation, if it doesn't exist, or submit patches for elements that are not ready yet.
Those are tracked in the QmlWeb Projects page.
If an element is labeled as «Ready to use» — build a minimal example to demonstrate the issue that you are experiencing, ensure that your code works with Qt QML, then file an issue with the code to reproduce it, describing the differences to Qt QML behaviour that you observe. Submitting a failing test (if no similar already exists) would also be helpful.
Submit an issue if it doesn't exist already. Be sure to include a minimal reproducible testcase.
Parser errors should go into qmlweb-parser repository.
Submit an issue if it doesn't exist already.
Note that «Wishlist» is not related to support stat of QML elements — those have a separate section, but to everything else, e.g. QmlWeb API requests, integration suggestions, and other things like that.
Please, redirect questions to QmlWeb Gitter chat. It uses GitHub auth, so should be available to everyone here without requiring additional registration.
To fix a bug, provide a pull request, preferably with a testcase.
Describe the changes in the commit message, see other commits in the repository for examples. Describe why the change is desired (ideally — by including a minimal reproducible testcase that it fixes).
If your pull request solves some failing test — be sure to mark it as non-failing (i.e. remove it from the failing tests list).
Try to make sure npm test passes before submitting a pull request (that would
be also checked by CI for every pull request).
A stub for a QML element is just a class that lists its properties, their types, signals, enums, and so on, but without implementation of the actual logic behind the class.
You will likely easily find some examples of those in the source code. If unsure, refer to the Projects page — projects there have a separate status for stubs.
Contributing stubs is useful not only because it saves time later on when writing the actual implementation, but also because it tells QmlWeb that that element exists, so it won't bail out when user tries to instantiate it.
If the stub is for a regular QML element, add it to the list of initialization tests. That will suffice as a testcase.
The goal is to support as much of the original Qt QML as possible, but even small incremental steps to that goal are fine. If your code adds limited support for an element or even implements some logic behind individual properties — be sure to submit it!
Note that for elements existing in Qt QML, incompatible QmlWeb-only functionality is not desired. So, please don't add any public properties or hooks that are not present in the Qt counterpart of the said elements. That is done to simplify maintaining compatibility in both directions.
Defining new elements that are not present in Qt is fine though, as long as
they are placed in a separate module (preferably QmlWeb.*). Example:
QmlWeb.Dom.
Testcases for the actual implementation are sometimes tricky. If possible — create a QtTest-based testcase, and/or a render test.
QmlWeb heavily relies on testcases, and those testcases are the best way to ensure compatibility with Qt QML. Tests are split in several categories, see below for more information.
Please, do not submit thirdparty tests, submit only those that you have written from scratch.
Failing tests that should work could also be submitted, by marking them as failing in /tests/failingTests.js.
Automatic tests placed in /tests/Auto that could be run on both Qt QML and QmlWeb to ensure identical results.
This is the preferred way of defining all logic/method tests (i.e. all tests except Render tests).
See QtTest documentation.
npm run qmltestrunner (or qmltestrunner -input tests/Auto) should pass on
the latest released Qt version.
Automatic render tests, each test consisting of a *.qml and a *.png file.
These tests are also runnable on both QmlWeb and Qt to ensure compatibility.
This is the preferred way of defining layout/positioning tests.
Things to note:
- Transparency is taken into account, if your testcase does not fill all the background — the png should include transparency for the test to pass.
- Some tests are not suitable to be a render test, as slight implementation differences are expected between various browsers (and even various Qt/os/platform versions). E.g. everything that includes text should probably not be a render test.
- Some color/opacity-rendering rounding implementation differs between browsers
by 1 color step (1/255, 0.4%). Such tests should be placed in
Render/Fuzzydirectory.
Running these tests with QMLWEB_SAVE_RENDER=1 would save the render output to
the tmp/Render directory. These could be used to quickly obtain the expected
output of a correctly performing testcase (given that it matches with Qt QML
rendering). It is also suggested to losslessly optimize the image before
commiting.
npm run qmltestrunner (or qmltestrunner -input tests/Render) should pass on
the latest released Qt version.
Initialization tests only check the presence of elements and the ability to instantiate them. They are defined in a single list, in file /tests/Initialize/runner.js.
Contribute initialization tests when writing stubs for new elements, one line per each element that should support direct instantiation from QML.
In most cases, you don't need those, unless you are fixing core/engine issues.
See QMLEngine tests for examples.
If the same test could be implemented using QtTest-based or render tests — use those instead.
As the compatibility is not perfect yet, there is a known list of currently failing tests. It is located in /tests/failingTests.js file.
Submitting failing tests with issues is encouraged, those are needed to reproduce the problem and to ensure it won't come back after being fixed.
If possible, submit a failing test each time you encounter an new issue that's not already tested.
The overall recommendation is to keep those tests as simple as possible, though. Complex tests are less likely to be accepted, try to make a minimal reproducible testcase.
Code maintenance and cleanup pull requests are accepted without appropriate
testcases. All the existing passing testcases should still pass (npm test).
Please provide an explanation why the change is desired, both in the commit description and in the pull request text.
This is similar to Fixing bugs in many aspects — just file an issue or a pull request if you think there is room for specific improvement.
Note that QML language itself and QML elements that exist in Qt QML are not documented here, the documentation for them resides upstream at https://doc.qt.io/.
As markdown files are linted, npm test (or npm run mdlint) should pass.
If you have any questions left after reading this document, feel free to ask them in QmlWeb Gitter chat.