---
id: zope-testbrowser
version: "8.0"
license: ZPL-2.1
license_treatment: unclear
maintenance: active
---

# zope.testbrowser — Programmable browser for functional black-box tests

License: unclear · Maintenance: active · Downloads: 129.4K/mo

## What it is and what it does

zope.testbrowser is a headless browser library designed for automated testing of web applications. It wraps WebTest and BeautifulSoup4 to provide a high-level API for navigating pages, filling forms, clicking links, and inspecting responses—all without a graphical browser. It's commonly used in functional black-box tests for WSGI applications, though it can work with any HTTP-based site.

The package handles cookies, redirects, form submission (GET and POST), file uploads, and control selection by name or label. It maintains browser state across requests and provides introspection of page content. Since version 5.0, it has used WebTest internally rather than mechanize, and requires explicit WSGI app setup rather than relying on Zope's testing infrastructure.

Use it for:

- Test form submission and validation in a WSGI application without running a browser
- Automate functional tests that verify user workflows across multiple pages
- Inspect and manipulate form controls programmatically in test suites
- Verify HTTP redirects, cookies, and response headers in integration tests
- Validate HTML link targets and form structure in automated test scenarios

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

zope.testbrowser provides a programmable web browser for automated testing of web applications and sites, with support for form interaction, cookie handling, and HTTP methods.

Yes, if you are testing a WSGI application or have a clear need for headless form automation in a test suite. The package is actively maintained, has no known vulnerabilities, and integrates well with standard testing frameworks. The main condition is that you must provide or wrap your application as WSGI; it is not a general-purpose web scraper. License clarity should be confirmed for your use case.

## Install

pip install zope-testbrowser
uv add zope-testbrowser
poetry add zope-testbrowser

## Installing zope.testbrowser

Before you install: Low friction install with a pure Python wheel. Actively maintained as of 2025-09-12 with recent Python version support (3.9–3.14). Ten runtime dependencies are all established packages; no compiled dependencies.

License in practice: Licensed under ZPL-2.1 (Zope Public License). License treatment is marked unclear in the fact sheet; review the full license terms before use in proprietary or copyleft-sensitive projects.

Quickstart:

pip install zope.testbrowser

from zope.testbrowser.wsgi import Browser

browser = Browser(wsgi_app=my_app)
browser.open('http://example.com')
control = browser.getControl(name='field_name')
control.value = 'test_value'

Requires a WSGI application instance; cannot test arbitrary websites without wrapping them in WSGI. Minimum Python 3.9.

Verify before relying:

- Whether ZPL-2.1 is compatible with your project's license or distribution model
- Performance characteristics when testing large forms or high-volume interactions
- Compatibility with modern JavaScript-heavy sites (package focuses on HTML/form testing)

## Package facts

- License: ZPL-2.1 (unclear)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 129.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

headless browser testing, automated web testing, WSGI application testing, functional web tests, form automation testing, HTTP client testing, programmatic browser control, testing, wsgi, headless-browser

[View on SkillFed](https://skillfed.io/packages/zope-testbrowser) · [View on PyPI](https://pypi.org/project/zope-testbrowser/)