Commits

Wolfgang Schnerring committed c7f0e33

Move integration documentation to Sphinx

  • Participants
  • Parent commits 550cfba

Comments (0)

Files changed (2)

File doc/integration.rst

 Integration
 ===========
 
+gocept.selenium provides integration with several web frameworks. Different
+frameworks require different dependencies; this is handled via setuptools
+extras of gocept.selenium (e.g. for Grok integration you need to require
+``gocept.selenium[grok]``).
+
+Generally, you need a test layer that handles the setup, and then have your
+tests inherit from the appropriate ``TestCase``.
+
+
 WSGI
 ----
 
+No extra requirements (simply ``gocept.selenium``).
 
-Zope3 / ZTK
------------
+This test layer takes a WSGI callable and runs it in a temporary HTTP server::
+
+    import gocept.selenium.wsgi
+    from mypackage import App
+
+    test_layer = gocept.selenium.wsgi.Layer(App())
+
+    class WSGIExample(gocept.selenium.wsgi.TestCase):
+
+        layer = test_layer
+
+        def test_something(self):
+            self.selenium.open('http://%s/foo.html' % self.selenium.server)
+            self.selenium.assertBodyText('Hello world!')
+
+
+Static files
+------------
+
+No extra requirements (simply ``gocept.selenium``).
+
+This test case provides a temporary directory (as ``self.documentroot``) that
+is served via HTTP where tests can put HTML files to examine::
+
+    import gocept.selenium.static
+
+    class StaticFilesExample(gocept.selenium.static.TestCase):
+
+        def test_something(self):
+            open(os.path.join(self.documentroot, 'foo.html'), 'w').write(
+                'Hello World!')
+                self.selenium.open('http://%s/foo.html' % self.selenium.server)
+                self.selenium.assertBodyText('Hello world!')
+
+
+Zope3 / ZTK (zope.app.testing)
+------------------------------
+
+Requires ``gocept.selenium[ztk]``.
+
+This test layer wraps your usual ZCMLLayer that is used for typical ZTK
+functional tests, and provides an HTTP server for testing::
+
+    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)
+
+    class ZTKExample(gocept.selenium.ztk.TestCase):
+
+        layer = selenium_layer
+
+        def test(self):
+            self.selenium.open('http://%s/foo.html' % self.selenium.server)
+            self.selenium.assertBodyText('Hello world!')
+
+
+Zope3 / ZTK (zope.app.wsgi)
+---------------------------
+
+If your ZTK application uses ``zope.app.wsgi.testlayer``, see `Grok`_ for
+integrating ``gocept.selenium``.
+
+
+Grok
+----
+
+Requires ``gocept.selenium[grok]``.
+
+This test layer groks your package and sets everything up so Selenium can
+access the application. You will probably want to setup your app in your test
+setup::
+
+    import gocept.selenium.grok
+    import transaction
+
+    selenium_layer = gocept.selenium.grok.Layer(my.package)
+
+    class GrokExample(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('Hello world!')
+
 
 
 Zope 2
 ------
 
+Requires ``gocept.selenium[zope2]``
+
+This test layer requires ``Testing.ZopeTestCase.layer.ZopeLiteLayer`` and
+provides an HTTP server for the tests. See
+``gocept.selenium.zope2.tests.test_zope212`` for details how to set this up.
+
+
+Zope 2 via WSGI
+---------------
+
+If your Zope 2 setup supports it, you can use the WSGI integration instead of a
+specialised Zope 2 integration to run your tests.
+
+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.
+
 
 Plone
 -----
 
+Requires ``gocept.selenium[plone]``.
 
-Grok
-----
+This test layer requires ``Products.PloneTestCase.laye.PloneSiteLayer`` and
+provides an HTTP server for the tests. See
+``gocept.selenium.plone.tests.test_plone{3,4}`` for details how to set this up.
+
+
+Zope 2 / Plone with plone.testing
+---------------------------------
+
+Requires ``gocept.selenium[plonetesting]``.
+
+``gocept.selenium`` provides a ``plone.testing.Layer`` at
+``gocept.selenium.plonetesting.SELENIUM`` that you can mix and match with your
+other layers, see ``gocept.selenium.plonetesting.testing`` with
+``gocept.selenium.plonetesting.tests.zope2``, and
+``gocept.selenium.plonetesting.testing_plone`` with
+``gocept.selenium.plonetesting.tests.plone{3,4}`` for details how to set this
+up.
+
+
+Converting Selenese HTML files
+------------------------------
+
+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 with a ``TestCase`` (based on ``gocept.selenium``
+and ``plone.testing``).
+
+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
+~~~~~
+
+::
+
+    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``.
+
+On Python-2.4, converthtmltests requires ``gocept.selenium[script]``.

File src/gocept/selenium/README.txt

-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``.