WebKit – patches and tests

More detailed, authoritative, and up-to-date information can be found in the Introduction to WebKit.

This is a follow up to my post on Building Webkit. Here, I’ll cover how to fix and test web-facing features in WebKit.

Naturally, first find the file that relates to the feature you are trying to fix (e.g., Navigator stuff would be in Navigator.cpp, etc.). 

A great search tool to help you find where things are, and to follow code symbols is SourceGraph. 

Tests

Like with any software, once you’ve prepared a patch, and you’ve built, you will need to test it to make sure it works and you haven’t regressed any existing code. 

In WebKit, tests are primarily in the LayoutTests/ folder. Web platform tests can be found in:

  • LayoutTests/imported/w3c/web-platform-tests/ – as the name suggests, imported from Web Platform Tests
  • LayoutTests/http/tests/ – these are modified tests to run on WebKit’s testing infrastructure over HTTP(S)
  • LayoutTests/fast/ – more tests!  

So you need to make sure you check in multiple locations. 

To run the tests, you use /Tools/Scripts/run-webkit-tests script. There are a few flags to be aware of: 

  • You need to specify the “target” for the test runner, which, if you followed my last blog post is --debug. 
  • The path can’t include “LayoutTests/” (see below) 
  • Important! If you test changes the result or adds new things, you need to add --reset-results. This will reset the results with whatever your run of the tests produces/changes.
  • At the time of writing, http(s) tests are restricted 127.0.0.1:8443 and localhost:8443, so a lot of WTP tests won’t work.   

For example, adding a new test + results:

./Tools/Scripts/run-webkit-tests --debug --reset-results fast/web-share/share-transient-activation-expired.html

Testing across multiple directories:

./Tools/Scripts/run-webkit-tests --debug fast/web-share/ http/tests/webshare/ imported/w3c/web-platform-tests/web-share/

The test development process is fairly straight forward. Poke around to see what libraries are available. 

Submitting your patch

Once your tests are passing, you are ready to send up a patch to WebKit! 

Firstly, make sure you have filed a bug for the thing you are adding or fixing!  

Then, to send your patch up to WebKit:

./Tools/Scripts/webkit-patch upload

It will ask you to provide some relevant information and generate various change logs for you. Check that they look ok. 

ProTip: I don’t recommend committing these changelogs to your working branch. If you rebase with the main branch, it makes a bit of a mess. They are auto-generated anyway, so just stash them or “git checkout path/to/changelog” them. 

Once upload everything for you to bugs.webkit.org.  

That will start the start the tests for various platforms (e.g., iOS, MacOS, etc.). If you are lucky, all tests will pass. If any fail, you will get an email with links to logs where you can find out what failed.

ProTip: make sure your errors spit out detailed messages when they fail. Otherwise, it will be difficult to know/where things have gone wrong (you often won’t get a stack trace, specially form JS). 

If any of the platforms fail (specially legacy ones, like Windows), you might need provide new text expectations. These are found in:

Layout/platform/ {win, mac-wk1, etc.} /TestExpectations

The TestExpectations above is a file (with no file extension).

Finalizing your patch

Once you get r+, you need to upload a new patch that modifies the changelog file with the reviewer’s name and email.