Commits

Anonymous committed 165946f Merge

merge

  • Participants
  • Parent commits 09a6e2a, 5e26c64

Comments (0)

Files changed (3)

 
 - Extract StaticFilesLayer to gocept.httpserverlayer.
 
+- Added `assertScreenshot` to visually compare rendered elements with a
+  master screenshot.
+
 
 2.0.0a2 (2013-01-09)
 --------------------
     https://bitbucket.org/gocept/gocept.selenium/raw/tip/CHANGES.txt
 
 
-buildout configuration
+Buildout configuration
 ----------------------
 
 gocept.selenium integrates with quite a lot of different testing approaches and
 
 Note that the zope210 and plone3 configurations require Python-2.4, while the
 others should work at least up to Python-2.6.
+
+Documentation
+-------------
+
+In order to build the Sphinx documentation, run the following command with a
+python, where sphinx is installed::
+
+    $ python setup.py build_sphinx
 Selenese API
 ------------
 
+.. _general-information:
+
+General information
+~~~~~~~~~~~~~~~~~~~
+
 The ``Selenese`` object available as ``self.selenium`` for each TestCase
 provides methods to control the browser, and to make assertions about things
 the browser sees.
 * Wait ``self.selenium.waitForElementPresent('id=foo')``
 * Negated Wait ``self.selenium.waitForNotElementPresent('id=foo')``
 
+Usage of assertScreenshot
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. NOTE:: ``assertScreenshot`` *needs* PIL. You might consider to require the
+          `screenshot` extra in your setup.py like so:
+          ``gocept.selenium[screenshot]``
+
+The ``assertScreenshot`` method allows you to validate the rendering of a HTML
+element in the browser. A screenshot of the element is saved in a given
+directory and in your test ``assertScreenshot`` takes a picture of the
+currently rendered element and compares it with the one saved in disk. The test
+will fail, if the screenshot and the taken picture do not match (within a given
+threshold).
+
+
+``assertScreenshot`` takes the following arguments:
+
+:name: A name for the screenshot (which will be appended with `.png`).
+:locator: A locator_ to the element, which will be captured.
+:threshold: If the difference [#1]_ in percent between the saved and current
+            image is greater than the threshold, a failure is triggered.
+            (defaults to 1)
+
+.. _locator : http://release.seleniumhq.org/selenium-remote-control/0.9.0/doc/dotnet/html/Selenium.html
+
+There is a capture mode available to help you in retrieving your master
+screenshot (which will be left on disk for comparison). When writing your test,
+set ``capture_screenshot`` on the `Selenese` object (see
+:ref:`general-information`) to ``True`` and the test run will save the
+screenshot to disk instead of comparing it. Before you check in your newly
+created screenshot, you should watch it to make sure, it looks like you
+expected it.  Setting ``capture_screenshot`` to ``False`` will compare the
+screenshot on disk with a newly created temporary image during the next test
+run.
+
+If ``assertScreenshot`` fails, paths to the following images are provided to
+you in the error message:
+
+:original: The path to the original image (the master image).
+:current: The path to the image taken in the current test run (from the
+          browser).
+:diff: The path to an image highlighting the differences between original and
+       current.
+
+If you would like to open the image showing the differences in an image viewer,
+set the environment variable ``SHOW_DIFF_IMG`` before running the test.
 
 Test helpers
 ------------
     The version test is only supported for Python >= 2.5. For Python < 2.5
     *only* a name check can be performed. Giving a version number will skip the
     test unconditionally.
+
+
+.. [#1] The difference is computed as normalised root mean square deviation of
+        the two images.