Metadata-Version: 1.0
Name: gocept.selenium
Version: 0.13
Summary: zope.testing layer that integrates Selenium-RC for any WSGI, Zope 2, Plone, ZTK, or grok application.
Home-page: http://packages.python.org/gocept.selenium
Author: Zope Foundation and Contributors
Author-email: ws@gocept.com
License: ZPL 2.1
Description: Selenium RC integration with zope.testing
        =========================================
        
        gocept.selenium integrates the `Selenium remote control`_ with your test suite
        for any WSGI, Plone, Zope 2, ZTK, or Grok application.
        
        .. _`Selenium remote control`: http://seleniumhq.org/projects/remote-control/
        
        .. contents::
        
        Prerequisites
        -------------
        
        Install Selenium RC by some means, e.g. by downloading a version from
        `seleniumhq.org`_ . We do not recommend using the
        ``collective.recipe.seleniumrc`` buildout recipe for this since we have had
        some bad experiences with it related to new versions of Selenium RC and
        Firefox.
        
        .. _`seleniumhq.org`: http://seleniumhq.org/download/
        
        
        
        Quick start for WSGI applications
        ---------------------------------
        
        You can test any WSGI application using gocept.selenium by doing:
        
        #. Require gocept.selenium for your tests.
        
        #. Create a layer for your tests::
        
            import gocept.selenium.wsgi
        
            from mypackage import App
        
            test_layer = gocept.selenium.wsgi.Layer(App())
        
        #. Inherit from `gocept.selenium.wsgi.TestCase`::
        
            class TestWSGITestCase(gocept.selenium.wsgi.TestCase):
        
                layer = test_layer
        
        Quick start for WSGI applications (Zope 2)
        ------------------------------------------
        
        When running Zope 2 as WSGI application you might see the following
        exception when running tests::
        
          File ".../repoze.retry-1.0-py2.7.egg/repoze/retry/__init__.py", line 55, in __call__
            cl = int(cl)
           ValueError: invalid literal for int() with base 10: ''
        
        To fix it you can use an additional middleware around your WSGI
        application: ``gocept.selenium.wsgi.CleanerMiddleware``. It also fixes an
        issue with ``wsgiref``. See comments in the code for more information.
        
        
        Quick start with ZTK (zope.app.testing)
        ---------------------------------------
        
        Assuming that you already have a package that uses ``zc.buildout`` and
        ``zope.app.testing``, you need to do this to enable Selenium tests:
        
        #. Add gocept.selenium to the list of eggs either in your setup.py, or in
           buildout.cfg, using the extra ``ztk``, i.e. ``gocept.selenium[ztk]``.
        
        #. Run buildout to install gocept.selenium and selenium (the Python bindings
           for Selenium RC).
        
        #. Create a layer for your tests, like this::
        
            import gocept.selenium.ztk
            import zope.app.testing.functional
            zcml_layer = zope.app.testing.functional.ZCMLLayer(
                'ftesting.zcml',
                __name__, __name__, allow_teardown=True)
            selenium_layer = gocept.selenium.ztk.Layer(zcml_layer)
        
           Essentially, the ``zcml_layer`` is what you would use for typical ZTK
           functional tests, and then you wrap it to create the ``selenium_layer``.
        
        #. Start writing tests that inherit ``gocept.selenium.ztk.TestCase``; make
           sure you set the ``layer`` attribute to ``selenium_layer`` on each test
           class.
        
        #. In your tests, use ``self.selenium`` to control Selenium RC, e.g. ::
        
            class MyTest(gocept.selenium.ztk.TestCase):
        
                layer = selenium_layer
        
                def test(self):
                    self.selenium.open('http://%s/foo.html' % self.selenium.server)
                    self.selenium.assertBodyText('foo')
        
        #. Run seleniumrc::
        
            $ java -jar /path/to/selenium-server.jar
        
        #. Run `bin/test` and see it work!
        
        
        Quick start with ZTK (zope.app.wsgi)
        ------------------------------------
        
        Assuming that you already have a package that uses ``zc.buildout`` and
        ``zope.app.wsgi.testlayer``, you should follow the steps described in `Quick
        start with Grok`_.
        
        
        Quick start with Zope 2/Plone (general)
        ---------------------------------------
        
        Essentially the same like `Quick start with ZTK (zope.app.testing)`_, just:
        
        * depend on `gocept.selenium[zope2]` resp. `gocept.selenium[plone]` instead
          of `gocept.selenium[ztk]`.
        
        * use ``gocept.selenium.zope2`` resp. ``gocept.selenium.plone`` instead of
          ``gocept.selenium.ztk``.
        
        Quick start with Zope 2/Plone (plone.testing)
        ---------------------------------------------
        
        If you use `plone.testing` to set up the test layers for your Zope2
        resp. Plone package you can follow these steps:
        
        #. Depend on `gocept.selenium[zope2]` resp. `gocept.selenium[plone]` in your
           `setup.py`.
        
        #. Create a `plone.testing` layer which loads your package and its ZCML
           configuration. (See documentation of `plone.testing` how to do this.)
        
        #. Create a layer for the selenium tests like this::
        
            selenium_layer = gocept.selenium.zope2.Layer(MY_PLONE_TESTING_LAYER)
        
           (You might need to exchange ``zope2`` by ``plone`` in this statement.)
        
        #. Create a test case and run the tests like described in `Quick start with
           ZTK (zope.app.testing)`_. But use ``gocept.selenium.zope2.TestCase`` resp.
           ``gocept.selenium.plone.TestCase`` instead of
           ``gocept.selenium.ztk.TestCase`` as test base class.
        
        
        
        Quick start with Grok
        ---------------------
        
        This layer works a little different than in the ZTK steps above. Instead of
        delegating to a (probably already existing functional testing) layer, you'll
        need a separate one for the selenium tests.
        
        #. Use the ``grok`` extra when requiring gocept.selenium.
        
        #. Create a layer for your tests::
        
            import gocept.selenium.grok
        
            selenium_layer = gocept.selenium.grok.Layer(my.package)
        
        #. Inherit from `gocept.selenium.grok.TestCase`. You will probably want to
           setup your app in your test setup::
        
            import transaction
        
            class MyTest(gocept.selenium.grok.TestCase):
                layer = selenium_layer
        
                 def setUp(self):
                     super(MyTest, self).setUp()
                     root = self.getRootFolder()
                     root['app'] = mypackage.App()
                     transaction.commit()
        
                 def test(self):
                     self.selenium.open('/app')
                     self.selenium.assertBodyText('foo')
        
        Quick start with plone.testing
        ------------------------------
        
        #. Use the ``plonetesting`` extra when requiring gocept.selenium.
        
        #. gocept.selenium provides a plone.testing.Layer,
           ``gocept.selenium.plonetesting.SELENIUM`` that you can mix and match with
           your other layers, see plonetesting.testing/plonetesting.tests.zope2 and
           plonetesting.testing_plone/plonetesting.tests.plone{3,4} for some examples
           of integrating with Zope2 and Plone, respectively.
        
        Selenium HTML tests conversion script
        -------------------------------------
        
        Selenium tests can be written in HTML tables.
        
        Their syntax is a bit clunky. But their development and debugging is eased a
        lot by using Selenium IDE Firefox extension.
        Selenium IDE provides both initial recording of tests and stepping through
        those tests.
        However, HTML tests have a main drawback : they are hard to include in a
        continuous integration system.
        
        ``gocept.selenium`` provides a script that converts a set of
        Selenium HTML tests into a Python module (based on ``gocept.selenium`` and
        ``plone.testing``). That Python module contains a ``TestCase`` that can be included in any
        ``zope.testing`` test suite.
        
        Using the ``converthtmltests`` script, the developer can use HTML tests - written,
        debugged and maintained with the Selenium tools -
        while being able to easily include those Selenium
        tests in a continuous integration system.
        
        Usage
        ~~~~~
        
        See hereunder an excerpt of the help provided by the script ::
        
            converthtmltests -l LAYER [options] directory
        
            options:
              -f FILE, --file=FILE  write tests to FILE
              -l LAYER, --layer=LAYER
                                    full python import path to layer instance
        
        The script gathers and converts all Selenium HTML tests found in the mentioned
        directory.
        
        The user must refer to a ``plone.testing`` layer by specifying its Python import path.
        That layer is set on the test case generated in the Python module.
        
        An output file can be specified. In case no output file name is specified,
        the module produced is named ``tests_all_selenium.py``.
        
        
        Controlling gocept.selenium through environment variables
        ---------------------------------------------------------
        
        You can configure the selenium server that gocept.selenium connects to from the
        command line. Selenium RC defaults to localhost:4444, but you can also connect
        to a selenium grid in your organization by using the following environment
        variables::
        
            GOCEPT_SELENIUM_SERVER_HOST=selenium.mycompany.com
            GOCEPT_SELENIUM_SERVER_PORT=8888
        
        If multiple browsers are connected to your selenium grid, you can choose the
        browser to run the tests with as such::
        
            GOCEPT_SELENIUM_BROWSER=*iexplore
        
        When you are running your selenium tests on a selenium grid, you need to
        instruct the browser which host and port to connect to::
        
            GOCEPT_SELENIUM_APP_HOST=10.0.0.15
            GOCEPT_SELENIUM_APP_PORT=8001
        
        When you are testing an application on one machine, you can access the running
        application from another machine if you set ``GOCEPT_SELENIUM_APP_HOST = 0.0.0.0``
        instead of the default ``localhost``.
        
        You can set the speed with which the tests are run through an environment
        variable::
        
            GOCEPT_SELENIUM_SPEED=500
        
        This example will introduce a 500 millisecond pause between tests.
        
        Similar packages
        ----------------
        
        zc.selenium -- integrates Selenium Core with zope.testing.
        
        
        Development
        -----------
        
        Report bugs at <https://intra.gocept.com/projects/projects/gocept-selenium/issues>.
        
        Get the latest source with ::
        
          svn co http://svn.zope.org/repos/main/gocept.selenium/trunk gocept.selenium
        
        
        
        Changes
        =======
        
        0.13 (2012-01-30)
        -----------------
        
        - Added a selenese assert type 'list' and added it to the window management
          query methods.
        
        - API expansion: added ``openWindow``.
        
        - API change: filter the result of ``getAllWindowNames`` to ignore 'null'.
        
        - backwards-compatible API change: ``selectWindow`` now selects the main
          window also when passed the window id ``None`` or no argument at all.
        
        - pinned compatible ZTK version to 1.0.1, grok version to 1.2.1, generally
          pinned all software packages used to consistent versions for this package's
          own testing
        
        
        0.12 (2011-11-29)
        -----------------
        
        - API expansion: added ``getAllWindow*`` and ``selectWindow``.
        
        
        0.11 (2011-09-15)
        -----------------
        
        - Added some notes how to test a Zope 2 WSGI application.
        
        - Described how to test a Zope 2/Plone application if using `plone.testing`
          to set up test layers.
        
        
        0.10.1 (2011-02-02)
        -------------------
        
        - Improvements on the README.
        
        - Wrote a quick start section for packages using ZTK but using
          ``zope.app.wsgi.testlayer`` instead of ``zope.app.testing``.
        
        - Allowed to use `regexp` as pattern prefix for regular expressions
          additionally to `regex` to be compatible with the docstring and the
          Selenium documentation.
        
        
        0.10 (2011-01-18)
        -----------------
        
        - Script that generates python tests from Selenium HTML tables.
          Reused from KSS project, courtesy of Jeroen Vloothuis, original author.
        
        - Using a URL of `Selenium RC` in README where version 1.0.3 can be
          downloaded (instead of 1.0.1) which works fine with Firefox on Mac OS X,
          too.
        
        0.9 (2010-12-28)
        ----------------
        
        - Provide integration with the recent testlayer approach
          (zope.app.appsetup/zope.app.wsgi) used by Grok (#8260).
        - Provide integration with plone.testing
        - Make browser and RC server configurable (#6484).
        - Show current test case in command log (#7876).
        - Raise readable error when connection to RC server fails (#6489).
        - Quit browser when the testrunner terminates (#6485).
        
        
        0.8 (2010-10-22)
        ----------------
        
        - Fixed tests for the StaticFilesLayer to pass with Python 2.4 through 2.7.
        - API expansion: ``getSelectOptions``
        
        
        0.7 (2010-08-16)
        ----------------
        
        - API expansion: ``getElementHeight|Width``, ``getCookie*`` and a few others.
        - lots of action methods (``mouse*`` among others)
        
        
        0.6 (2010-08-09)
        ----------------
        
        - assertXpathCount now also takes ints (#7681).
        
        - API expansion: add ``isChecked`` to verify checkboxes, ``runScript``,
          ``clickAt``, ``getLocation``, ``getSelectedValue``, ``getSelectedIndex``.
        
        - The ``pause`` method uses float division now. Pauses where implicitly rounded
          to full seconds before when an int was passed.
        
        - The name of the factored test layer contains the module of the bases now. The
          name is used by zope.testrunner distinguish layers. Before this fix selenium
          layers factored from base layers with the same names but in different modules
          would be considered equal by zope.testrunner.
        
        - The factored ZTK layer cleanly shuts down the http server in tearDown now.
          This allows to run different selenium layers in one go.
        
        
        0.5 (2010-08-03)
        ----------------
        
        - Add a static files test layer for running selenium tests against a set
          of static (HTML) files.
        - Patterns now also work with multiline strings,
          i. e. 'foo*' will match 'foo\nbar' (#7790).
        
        
        0.4.2 (2010-05-20)
        ------------------
        
        - API expansion: ``*keyDown``, ``*keyUp``, ``keyPress``.
        
        
        0.4.1 (2010-04-01)
        ------------------
        
        - API expansion: added ``getSelectedLabel``.
        
        - Ignore the code of a server's response when calling `open`. The default
          behaviour of SeleniumRC changed between 1.0.1 and 1.0.2 but we want the old
          behaviour by default.
        
        
        0.4 (2010-03-30)
        ----------------
        
        - API expansion: add ``getLocation`` to retrieve currently loaded URL in
          browser.
        
        - API expansion: added ``waitForPopUp``, ``selectPopUp``, ``deselectPopUp``
          and ``close``.
        
        - API expansion: added ``verifyAlertPresent``, ``verifyAlertNotPresent`` and
          ``waitForAlertPresent``.
        
        - Usability: raise a better readable exception when an unimplemented selenese
          method is called.
        
        - Usability: raise failure exceptions that convey the name of the failed
          assertion in spite of some lambdas wrapped around it.
        
        
        0.3 (2010-01-12)
        ----------------
        
        - Extracted 'host' and 'port' as class attributes of gocept.selenium.ztk.Layer
          so subclasses can override them; stopped hardcoding 8087 as the server port.
        
        
        0.2.1 (2009-12-18)
        ------------------
        
        - Fix incomplete sdist release on PyPI.
        
        
        0.2 (2009-12-18)
        ----------------
        
        - Make Zope 2 test server reachable from the outside.
        - Implemented getTitle/assertTitle/waitForTitle/etc.
        
        
        0.1 (2009-11-08)
        ----------------
        
        - first release
        
Platform: UNKNOWN
