Add a Testing API reference (plone.app.testing + plone.testing) by jensens · Pull Request #2097 · plone/documentation

jensens · 2026-07-24T22:58:00Z

Builds on #2094 (the backend testing chapter). Targets backend-testing-docs; merge #2094 first. GitHub will retarget this to 6.0 once #2094 lands.

What

Adds an autodoc-generated API reference and a deeper layer-model explanation to the developer-guide/testing chapter, plus two how-tos. It covers both testing packages as one toolkit, because a test author does not care whether a symbol lives in plone.app.testing or plone.testing.

Page
`testing-api-reference.md`	Organized by task: layer model, pre-built layers & fixtures, browser & HTTP, helpers, sandboxing primitives, constants. Symbols documented at their canonical location (e.g. `pushGlobalRegistry` under `plone.testing.zca`, with a re-export note), from both packages.
`how-testing-layers-work.md`	Deepened with the fixture/lifecycle split.
`install-add-ons-in-tests.md`, `drive-the-test-browser.md`	Two how-tos absorbing the test-specific patterns from `plone.app.testing`'s README.

How the reference is built

sphinx-autodoc2, which analyses the sources statically. So:

No Plone is installed in the docs build. sphinx.ext.autodoc would need to import plone.app.testing, which pulls in ~226 packages (all of Plone). autodoc2 needs neither. Both packages are added as source-only submodules.
It coexists with the existing sphinx.ext.autodoc (used by plone.api).
The plone.testing submodule pins master; the Layer class docstring there is currently a one-liner. Expand the Layer base class docstring plone.testing#134 enriches it, after which a submodule bump renders it in full. The reference is complete either way; that entry just gets richer.

Notes

Browser is a re-export from a private module (plone.testing._z2_testbrowser), which autodoc2 cannot resolve, so it is documented as a short prose entry.
Legacy ZServer (PLONE_ZSERVER, PLONE_FTP_SERVER) is noted, not documented — Plone 6 runs on WSGI.
Vale is clean on the new pages; the vocabulary additions it needed are included and sorted.

🤖 Generated with Claude Code

Extends the developer-guide/testing chapter with an autodoc-generated API reference and a deeper layer-model explanation, covering both testing packages as one toolkit (a test author does not care which package a symbol lives in). - testing-api-reference.md: organized by task (layer model, pre-built layers and fixtures, browser and HTTP, helpers, sandboxing primitives, constants), pulling symbols from both packages at their canonical location, with re-exports noted. Generated by sphinx-autodoc2, which reads the sources statically -- so no Plone is installed in the docs build. Both packages are added as source-only submodules. - how-testing-layers-work.md: deepened with the fixture/lifecycle split. - install-add-ons-in-tests.md, drive-the-test-browser.md: two how-tos that absorb the test-specific patterns from plone.app.testing's README. conf.py gains the autodoc2 extension beside the existing sphinx.ext.autodoc (used by plone.api); the two coexist. Legacy ZServer is noted, not documented. Vale is clean on the new pages.

…lone/plone.testing#134)

gforcada

Very nice! 🌟 I have only a few suggestions for improvements rather than blockers 👍🏾

gforcada · 2026-07-28T07:42:20Z

 sphinxext-opengraph
 sphinxcontrib.mermaid
 vale
+sphinx-autodoc2  # developer-guide/testing plone.app.testing reference


keep this sorted please :)

gforcada · 2026-07-28T07:45:12Z

 # Don't show class signature with the class' name.
 autodoc_class_signature = "separated"

+# -- Options for autodoc2 (plone.app.testing reference) -----------------------


While nice for the PR itself, it might outdate very quickly this constant reference that autodoc2 is added due to plone.app.testing. As soon, say, plone.api is used as well, we will not go around and update all the references.

git blame is much better at that for this purpose IMHO

gforcada · 2026-07-28T07:47:33Z

+
+## Reference and background
+
+- {doc}`testing-api-reference`: the layers, fixtures, helpers, and sandboxing, from both packages.


which both packages? 🤔

gforcada · 2026-07-28T07:52:56Z

+
+## Layers compose through bases
+
+A layer declares its bases—the layers it builds on—through `defaultBases` or the `bases` argument.


If both (defaultBases and bases) serve the same purpose (which I have no idea right now) should we only mention one? Otherwise readers might just wonder exactly that: which one to use 🤷🏾 ?

gforcada · 2026-07-28T07:56:41Z

+It uses the helpers from {doc}`testing-api-reference`.
+The examples assume a layer whose fixture already loaded your add-on's ZCML—see {doc}`write-a-testing-layer`.
+
+If you use pytest, {doc}`pytest-plone </developer-guide/testing/pytest>` also offers an `installer` fixture and an `@pytest.mark.portal(profiles=[...])` marker that do the same thing with less boilerplate.


that could be an admonition? to better highlight it?

gforcada · 2026-07-28T08:00:34Z

+You import from whichever package a symbol lives in, but from a test author's point of view they are one toolkit, so this page is organized by task rather than by package.
+Each symbol is documented at its canonical location; re-exports are noted.


that should be an admonition IMHO

gforcada · 2026-07-28T08:11:06Z

+
+```{important}
+`zope.testbrowser` runs entirely in Python and does **not** run JavaScript.
+Use it for server-rendered pages (Classic UI). To test a Volto frontend, use the Volto documentation's end-to-end testing tools instead.


Should we already name Blicca here? otherwise we keep the old name still around...

As for the Volto docs, do we have a link within the docs we can point to? 🤔

we should at least name both Blicca (formelry ClassicUI) or such.

- Sort sphinx-autodoc2 into requirements.txt. - Make the autodoc2 conf.py comments generic instead of naming a specific consumer, which would outdate. - Name the two packages explicitly in the chapter index instead of 'both packages'. - Clarify defaultBases vs the bases argument (class default vs the instantiation-time exception) rather than listing them as equivalent. - Highlight the pytest alternative in the install how-to as a tip. - Name Blicca (formerly Classic UI) and link the Volto testing docs in the test-browser how-to. Kept the reference intro as prose rather than a third admonition, per the Plone docs guidance to use admonitions sparingly.

jensens · 2026-07-28T13:22:22Z

Thanks @gforcada! Addressed in the last commit:

requirements.txt — sorted sphinx-autodoc2 into place.
conf.py comment — good point about it outdating. Made the comments generic ("static API docs from source, no package import needed") instead of naming a specific consumer, so they stay true no matter which packages use autodoc2.
"which both packages?" — now names them: "across plone.app.testing and plone.testing".
pytest note — made it a {tip}.
Blicca — done, and thanks for the nudge: "Blicca, the frontend formerly called Classic UI", with a link to the Volto testing docs for the other side. (The rest of the docs still say "Classic UI", so this page is slightly ahead — happy to align once the wider rename lands.)

Two where I did something a bit different, curious what you think:

defaultBases vs bases — they aren't quite the same purpose, so rather than drop one I clarified when each applies: you set defaultBases on a reusable layer class, and pass bases only when instantiating a layer directly to combine existing ones (the exception, not the rule). That should answer the "which one" question without hiding the override.
The intro "documented at its canonical location" note — I kept it as prose rather than a third admonition. The page already has two (the legacy-ZServer warning and the re-export note), and the Plone docs style guide asks for admonitions sparingly, so I didn't want to spend a third on orientation text. Easy to switch if you feel strongly.

github-project-automation Bot added this to Plone Documentation Jul 24, 2026

github-project-automation Bot moved this to New in Plone Documentation Jul 24, 2026

Bump plone.testing submodule to include the enriched Layer docstring (p…

fdace45

…lone/plone.testing#134)

jensens mentioned this pull request Jul 24, 2026

Add a Testing chapter for backend packages #2094

Open

jensens requested a review from stevepiercy July 24, 2026 23:18

gforcada reviewed Jul 28, 2026

View reviewed changes

jensens added 2 commits July 28, 2026 15:06

Merge branch 'backend-testing-docs' into plone-app-testing-docs

9e3592c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add a Testing API reference (plone.app.testing + plone.testing) - #2097

Add a Testing API reference (plone.app.testing + plone.testing)#2097
jensens wants to merge 4 commits into
backend-testing-docsfrom
plone-app-testing-docs

jensens commented Jul 24, 2026

Uh oh!

gforcada left a comment

Uh oh!

gforcada Jul 28, 2026

Uh oh!

gforcada Jul 28, 2026

Uh oh!

gforcada Jul 28, 2026

Uh oh!

gforcada Jul 28, 2026

Uh oh!

gforcada Jul 28, 2026

Uh oh!

gforcada Jul 28, 2026

Uh oh!

gforcada Jul 28, 2026

Uh oh!

jensens Jul 28, 2026

Uh oh!

jensens commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Reference and background

		- {doc}`testing-api-reference`: the layers, fixtures, helpers, and sandboxing, from both packages.


		## Layers compose through bases

		A layer declares its bases—the layers it builds on—through `defaultBases` or the `bases` argument.

		You import from whichever package a symbol lives in, but from a test author's point of view they are one toolkit, so this page is organized by task rather than by package.
		Each symbol is documented at its canonical location; re-exports are noted.

Uh oh!

Uh oh!

Conversation

jensens commented Jul 24, 2026

What

How the reference is built

Notes

Uh oh!

gforcada left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jensens commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants