Skip to content
Switch branches/tags


Build Status

Needle is a tool for testing visuals with Selenium and nose.

It checks that visuals (CSS/fonts/images/SVG/etc.) render correctly by taking screenshots of portions of a website and comparing them against known good screenshots. It also provides tools for testing calculated CSS values and the position of HTML elements.


This is what a Needle test case looks like:

from needle.cases import NeedleTestCase

class BBCNewsTest(NeedleTestCase):
    def test_masthead(self):
        self.assertScreenshot('#blq-mast', 'bbc-masthead')

This example checks for regressions in the appearance of the BBC's masthead.


Full documentation available on Read the Docs.

If you'd like to build the documentation yourself, first install sphinx:

pip install sphinx

Then run:

cd docs
make html

The documentation will then be available browsable from docs/_build/index.html.

Running Needle's test suite

First install tox (usually via pip install tox). Then:

$ tox