Read first
- Reftest overview
- How to run Reftests
- How to write Reftests
- How to write more Reftests
- Understanding the Reftest log file
Testing invalidation
Testing that a document displays correctly once it has loaded is only one part of testing rendering. Another part is testing invalidation - testing that when a document is changed after it has finished loading and displaying, that the browser correctly "invalidates" the parts of the screen that should change so that the screen displays the correct output the next time it is repainted. Invalidation tests check both that the internal state of the document has been updated correctly, and that the browser then correctly invalidates and repaints the appropriate parts of the screen.
In order to test invalidation it is important that invalidation tests let the document completely finish loading and displaying before making the changes for which invalidation and repainting is to be tested. Making the changes before the document has completely finished loading and painting would mean that the test may not actually test the browser's invalidation logic, since the changed parts of the document may end up displaying correctly purely due to a pending post-load paint.
To write an invalidation Reftest requires three extra steps. First you need to add class="reftest-wait" to the root element in the test to tell the Reftest framework not to check the rendering as soon as the test finishes loading and moving on to the next test. Next you need to add a listener for the MozReftestInvalidate event, and only make the changes you want to test invalidation for after that event has fired. Third, you need to remove reftest-wait from the root element's class attribute to tell the Reftest framework that the test is now ready to have its rendering tested.
The reason for using the MozReftestInvalidate event is because a document's initial painting is not typically finished when the load event fires. It would be possible to try and wait for the initial rendering to be done using a setTimeout, but that would be unreliable, and just as bad, it can increase the time it takes to run a test many times over (which when you're running thousands of tests can really slow things down). The MozReftestInvalidate event is designed to fire as soon after the initial rendering of the document is finished as possible, but never before. The Reftest framework fires one MozReftestInvalidate event at the document root element for a reftest-wait test when it is safe to make changes that should test invalidation. The event bubbles up to the document and window so you can set listeners there too.