Metadata-Version: 2.1
Name: z3c.etestbrowser
Version: 4.0
Summary: Extensions for zope.testbrowser
Home-page: https://github.com/zopefoundation/z3c.etestbrowser
Author: Christian Theune
Author-email: zope-dev@zope.dev
License: ZPL 2.1
Keywords: zope3 testbrowser lxml
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Framework :: Zope :: 3
Requires-Python: >=3.7
Provides-Extra: test
License-File: LICENSE.txt

=====================================
Extensions for the Zope 3 testbrowser
=====================================

This package is intended to provide extended versions of the Zope 3
testbrowser_. Especially those extensions that introduce dependencies to more
external products, like lxml.

.. _testbrowser: https://pypi.org/project/zope.testbrowser/

.. contents::

Extension: lxml-support
=======================

All HTML pages are parsed and provided as an element-tree.


Extended testbrowser
--------------------

This package provides some extensions to ``zope.testbrowser``.  These are not
included in the core because they have extra dependencies, such as ``lxml``.


Requirements
~~~~~~~~~~~~

 - lxml


etree support
~~~~~~~~~~~~~

The extended test browser allows parsing of the result of a request into an
etree using lxml (if the content type is text/html or text/xml).

This is useful to perform more detailed analysis of web pages using e.g. XPath
and related XML technologies.

Example:

  >>> from z3c.etestbrowser.testing import ExtendedTestBrowser
  >>> browser = ExtendedTestBrowser()
  >>> browser.open("http://localhost/")
  >>> print(browser.contents)
  <!DOCTYPE ...>
  ...
  </html>
  >>> browser.etree
  <Element html at ...>
  >>> browser.etree.xpath('//body')
  [<Element body at ...>]


Strict XML
++++++++++

It is possible to force the test browser to use the xml parser:

  >>> browser.xml_strict
  False
  >>> browser.xml_strict = True
  >>> browser.open("http://localhost/")
  >>> browser.etree
  <Element {http://www.w3.org/1999/xhtml}html at ...>
  >>> browser.etree.xpath(
  ...     '//html:body', namespaces={'html': 'http://www.w3.org/1999/xhtml'})
  [<Element {http://www.w3.org/1999/xhtml}body at ...>]

LXML unicode support
++++++++++++++++++++

A couple of variations of libxml2 might interpret UTF-8 encoded strings
incorrectly. We have a workaround for that. Let's have a look at a view that
contains a German umlaut:

  >>> browser.xml_strict = False
  >>> browser.open('http://localhost/lxml.html')
  >>> browser.etree.xpath("//span")[0].text == u'K\xfcgelblitz.'
  True

Invalid XML/HTML responses
++++++++++++++++++++++++++

Responses that contain a body with invalid XML/HTML will cause an error when
accessing the etree or normalized_contents attribute, but will load fine for
general TestBrowser use:

  >>> browser.open("http://localhost/empty.html")
  >>> browser.contents
  ''
  >>> browser.etree
  Traceback (most recent call last):
  ValueError: ...
  >>> browser.normalized_contents
  Traceback (most recent call last):
  ValueError: ...


HTML/XML normalization
~~~~~~~~~~~~~~~~~~~~~~

The extended test browser allows normalized output of HTML and XML which makes
testing examples with HTML or XML a bit easier when unimportant details like
whitespace are changing:

  >>> browser.open('http://localhost/funny.html')
  >>> print(browser.contents)
  <html>
    <head>
      <title>Foo</title>
  </head>
      <body>
            <h1>
        Title
      </h1>
          </body>
              </html>
  <BLANKLINE>

versus

  >>> print(browser.normalized_contents)
  <html>
    <head>
      <title>Foo</title>
    </head>
    <body>
      <h1>
        Title
      </h1>
    </body>
  </html>


Using testbrowser on the internet
---------------------------------

The ``z3c.etestbrowser.browser`` module exposes an ``ExtendedTestBrowser``
class that simulates a web browser similar to Mozilla Firefox or IE.

    >>> from z3c.etestbrowser.browser import ExtendedTestBrowser
    >>> browser = ExtendedTestBrowser()

It can send arbitrary headers; this is helpful for setting the language value,
so that your tests format values the way you expect in your tests, if you rely
on zope.i18n locale-based formatting or a similar approach.

    >>> browser.addHeader('Accept-Language', 'en-US')

The browser can `open` web pages:

    >>> browser.open('https://www.w3.org')
    >>> print(browser.contents)
    <!DOCTYPE html ...
    ...The World Wide Web Consortium (W3C) is an international community...


=======
CHANGES
=======

4.0 (2023-02-21)
================

- Drop support for Python 2.7, 3.5, 3.6.

- Add support for Python 3.8, 3.9, 3.10, 3.11.

- Drop deprecated support for ``python setup.py test``.

- Drop deprecated ``z3c.etestbrowser.wsgi``.


3.0.1 (2019-03-05)
==================

- Fix deprecation declaration in ``.wsgi``.


3.0 (2019-03-04)
================

Backwards incompatible changes
------------------------------

- Add support for ``zope.testbrowser >= 5.0`` which speaks WSGI this requires
  tests to be updated to WSGI.

- Deprecate ``z3c.etestbrowser.wsgi`` which used to contain the WSGI variant
  as it is now the default.

- Drop the ``zope.app.testing`` extra introduced in version 2.0.0 as
  it dropped its special ``zope.testbrowser`` support.

- Drop ``.browser.ExtendedTestBrowser.pretty_print`` as its requirements are
  deprecated or even removed from Python's StdLib.

- Adapt the code to newer ``lxml`` versions which no longer raise an exception
  if the string to be parsed by ``lxml.etree`` is empty. We now raise a
  ``ValueError`` in this case.

Features
--------

- Add support for Python 3.6 up to 3.7.


2.0.1 (2015-11-09)
==================

- Fix `over_the_wire.txt`


2.0.0 (2011-10-13)
==================

- No longer depending on ``zope.app.wsgi`` but on ``zope.testbrowser`` >= 4.0
  for the WSGI flavor of testbrowser.

- Added a `zope.app.testing` extra. You should use this extra if you want to
  use the browser in ``z3c.etestbrowser.testing``. (The base testbrowser used
  there has been moved from ``zope.testbrowser`` to ``zope.app.testing`` in
  version 4.0.)

- Renamed ``z3c.etestbrowser.wsgi.ExtendedTestBrowser`` to ``Browser`` for
  equality with ``zope.testbrowser`` but kept ``ExtendedTestBrowser`` for
  backwards compatibility.

1.5.0 (2010-08-22)
==================

- Added ``z3c.etestbrowser.wsgi.ExtendedTestBrowser``, a variant that can be
  used when the test layer was set up using ``using
  zope.app.wsgi.testlayer``.


1.4.0 (2010-07-08)
==================

- Took ``zope.securitypolicy`` refactoring and ``zope.testing.doctest``
  deprecation into account.

- Added ``z3c.etestbrowser.browser.ExtendedTestBrowser``, a variant that
  speaks HTTP instead of directly talking to the publisher talks to the
  publisher, see `Using testbrowser on the internet`_.


1.3.1 (2010-01-18)
==================

- Added doctest to `long_description` to show up on pypi.

1.3.0 (2009-07-23)
==================

- Updgraded pacakge to lxml 2.2.

- Fixed bug with `normalized_contents` which would break the `open` function
  of test browser if content wasn't parsable as HTML/XML.

1.2.0 (2008-05-29)
==================

- Added `normalized_contents` attribute that reindents and normalizes the
  etree structure of a document and allows easier to read HTML/XML examples in
  doctests.
