This Wiki page is edited by participants of the Protocols and Formats Working Group. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Working Group participants, WAI, or W3C. It may also have some very useful information.
ARIA/WebKit Automated Tests
Some web developers are interested in contributing to WebKit, but aren't sure where to get started.
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.
# 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.
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).
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.
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="firstname.lastname@example.org" --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 <email@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.