Some web developers are interested in contributing to WebKit, but aren't sure where to get started.

Layout tests are a good place to start, as they rely on technologies already familiar to web devs, like HTML, CSS, and JavaScript. Some of the steps in test creation, validation, and source submission are not very obvious, so this page covers how web developers can contribute to the open source WebKit project by contributing layout tests, including but not limited to tests related to validating the accessibility mappings.

First create an account on the WebKit bug tracker, and create a new bug, titled something logical like "Accessibility layout test for mapping form ARIA roles" or "Modify layout test accessibility/foo to include additional element tests." Keep track of the bug link by adding yourself to the CC list.

Checking out and building WebKit

Open Terminal and check out the source using SVN . (Note: the auto-submit bot does submit Git patches at this time.)

cd ~/svn/  # Your source code directory can be anywhere.
svn checkout https://svn.webkit.org/repository/webkit/trunk WebKit

This initial checkout may take a few hours, and may time out during the process. Don't worry if it times out, just update the directory rather than starting over.

cd WebKit
svn update  # repeat as necessary until this completes.

Add the WebKit scripts directory to your path.

mate ~/.profile  # This assumes you have TextMate. Edit the file any way you prefer.

Notice a line declaring the PATH environment variable. If you have it, modify it. If you do not have it, add it.

export PATH=/usr/bin:/opt/local/bin:/opt/local/sbin:$PATH

# modify your PATH to include the WebKit scripts directory:
export PATH=/usr/bin:/opt/local/bin:/opt/local/sbin:~/svn/WebKit/Tools/Scripts:$PATH

Close your Terminal window and open a new one. Run the update script, and then the build script.

update-webkit
build-webkit

Depending on your machine, this build step may take an hour or more. This is a good time to get some lunch.

Creating your Layout Test

First, read the WebKit code style guidelines. Then start by reviewing the layout tests in ./LayoutTests/accessibility. When you're ready to create a new test, add a file (e.g. foo.html) to the directory. Do not add the corresponding expectation file (e.g. foo-expected.txt), as this will be generated by the test run script. If you're attempting to verify specific accessibility attributes, review the IDL definitions of AccessibilityController and AccessibilityUIElement, and compare attributes (such as role, subrole, and helptext) and methods (such as titleUIElement, focusedElement, and accessibleElementById).

./Tools/WebKitTestRunner/InjectedBundle/Bindings/AccessibilityController.idl
./Tools/WebKitTestRunner/InjectedBundle/Bindings/AccessibilityUIElement.idl

Many standard layout tests can be initially tested directly in a browser window. However, these accessibility properties are only available inside the context of the test runner, so the easiest way to verify the output of these properties is by using the test runner script.

run-webkit-tests ./LayoutTests/accessibility/foo.html

This will either pass or launch a copy of WebKit showing the failure details and output. If you've modified an existing test, you'll need to remove the corresponding expectation file (e.g. foo-expected.txt), but don't do this until you're sure your new output is correct. When generating the new expectation file (for new tests or if you've removed an existing one), the test runner script will throw an error the first time that the expectation file is missing, but you won't see this error on subsequent test runs.

Once you think you're done, run the check-webkit-style script and clean up any errors. Update WebKit again, re-run the test runner script, and verify you're ready to go.

check-webkit-style ./LayoutTests/accessibility/foo.html
update-webkit
run-webkit-tests ./LayoutTests/accessibility/foo.html

Now you're ready to submit a patch.

Submitting a Patch to WebKit

Add your newly created files (both the layout test and the generated expectation file) to your local Subversion repo.

svn add ./LayoutTests/accessibility/foo.html
svn add ./LayoutTests/accessibility/foo-expected.txt

Check the Subversion status to make sure the diff does not include any unexpected modifications, then run the prepare-Changelog script.

svn st
prepare-ChangeLog --name="First Last" --email="name@example.com" --bug=#### 

The script will modify the ChangeLog file to prepend the following stubbed change log.

Edit ./LayoutTests/ChangeLog and make the changes denoted in bold following the pound sign.

2013-01-16  First Last  <name@example.com> # Verify your name and email.

    Need a short description (OOPS!). # Replace entire line with the bug title.
    Need the bug URL (OOPS!). # Replace entire line with the bug URL.

    Reviewed by NOBODY (OOPS!). # Leave this line untouched for the commit bot.

    # Write a description of the entire change here...

    * accessibility/foo.html: Added.
    * accessibility/foo-expected.txt: Added.

Once you've edited the change log, prepare a patch file.

svn-create-patch > ~/Desktop/foo-layout-test.patch

Review the file (formatted diff) to make sure everything looks right, then attach it to the WebKit bug. The submission bot will run tests against the available platforms. If a test fails on a particular platform, either fix the failure, or bypass the failure in that platform's TestExpectations file, and submit a replacement patch. For example bypass reasons, see: ./LayoutTests/platform/<platform>/TestExpectations

Once you're sure all the platform tests pass, set the bug's review flag to "review?".

A reviewer may suggest additional changes; if so, make the changes and submit another patch. Once the test passes all platforms and a reviewer has approved the change, the reviewer will flag it for the commit queue, and the patch should land with 15 minutes.

Congratulations, you're done! Additional information can be found on WebKit's contributing code page.