From 4a4bae55d6fc535c06255f5342a52369e49621cf Mon Sep 17 00:00:00 2001 From: "Jens W. Klein" Date: Sat, 25 Jul 2026 00:55:42 +0200 Subject: [PATCH] Expand the Layer base class docstring The class had only 'A base class for layers.'. Describe the setUp/tearDown and testSetUp/testTearDown lifecycle, the resource mapping (self[key]), and composition through bases. Groundwork for an autodoc-generated API reference in the Plone documentation. Docstring only, no behaviour change. --- news/+enrich-layer-docstring.documentation | 3 +++ src/plone/testing/layer.py | 22 +++++++++++++++++++++- 2 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 news/+enrich-layer-docstring.documentation diff --git a/news/+enrich-layer-docstring.documentation b/news/+enrich-layer-docstring.documentation new file mode 100644 index 0000000..ddae7aa --- /dev/null +++ b/news/+enrich-layer-docstring.documentation @@ -0,0 +1,3 @@ +Expand the ``Layer`` base class docstring to describe the set-up/tear-down and per-test lifecycle, the resource mapping, and layer composition through bases. +This makes it usable as an API reference. +[jensens] diff --git a/src/plone/testing/layer.py b/src/plone/testing/layer.py index c88af2b..56437e3 100644 --- a/src/plone/testing/layer.py +++ b/src/plone/testing/layer.py @@ -130,7 +130,27 @@ def _resourceResolutionOrder(self, instance): class Layer(ResourceManager): - """A base class for layers.""" + """Base class for a test layer: a shareable, composable test fixture. + + A layer is set up once and shared by every test that uses it, which is + what makes expensive fixtures such as a running Zope or a Plone site + affordable. It has two pairs of lifecycle methods, meant to be + overridden: + + - ``setUp`` and ``tearDown`` run **once**, around the whole group of + tests that share the layer. Do the expensive work here. + - ``testSetUp`` and ``testTearDown`` run **around every test**. Do the + cheap per-test isolation here. + + A layer is also a mapping of *resources*. Set-up code stores objects in + it by key with ``self[key] = value``, and tests read them back with + ``self.layer[key]``. Resources are stacked, so a layer's value shadows a + base's and is restored on tear-down. + + Layers compose through **bases**: set ``defaultBases`` to a tuple of + layer instances, or pass ``bases`` to the constructor. Each base is set + up once, before this layer, and reused rather than rebuilt. + """ # Set this at the class level to a tuple of layer *instances* to treat # as bases for this layer. This may be overridden by passing a tuple