Add @pytest.mark.portal marker and supporting fixtures (#37)

ericof · ericof · commit 3e98890feb80 · 2026-04-12T12:15:57.000-03:00
Introduce a portal marker that lets tests declare GenericSetup profiles,
content, and roles inline — without overriding the portal fixture.

New session-scoped fixtures: apply_profiles, create_content, grant_roles.

Also: bump Plone to 6.1.4, add plone-stubs to test deps, update mx.ini.
diff --git a/.gitignore b/.gitignore
@@ -43,3 +43,7 @@ var/
 constraints*.txt
 requirements*.txt
 .coverage*
+.*_cache/
+
+# Local Claude context (not for sharing)
+.claude/*.local.*
diff --git a/Makefile b/Makefile
@@ -28,10 +28,17 @@ BACKEND_FOLDER=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
 ifdef PLONE_VERSION
 PLONE_VERSION := $(PLONE_VERSION)
 else
-PLONE_VERSION := 6.1.1
+PLONE_VERSION := 6.1.4
+endif
+
+ifdef CI
+UV_VENV_ARGS :=
+else
+UV_VENV_ARGS := --python={{ cookiecutter.__supported_versions_python[0] }}
 endif
 
 VENV_FOLDER=$(BACKEND_FOLDER)/.venv
+export VIRTUAL_ENV=$(VENV_FOLDER)
 BIN_FOLDER=$(VENV_FOLDER)/bin
 
 # Environment variables to be exported
diff --git a/README.md b/README.md
@@ -316,6 +316,83 @@ def test_last_version(profile_last_version):
     assert version == "1000"
 
 ```
+
+### apply_profiles
+
+|  |  |
+| --- | --- |
+| Description | Function to apply GenericSetup profiles to a Plone site. |
+| Required Fixture | **integration** |
+| Scope | **Session** |
+
+```python
+def test_with_profile(portal, apply_profiles):
+    """Test that a profile can be applied."""
+    apply_profiles(portal, ["my.addon:testing"])
+```
+
+### create_content
+
+|  |  |
+| --- | --- |
+| Description | Function to create content items in a Plone site as the site owner. |
+| Required Fixture | **integration** |
+| Scope | **Session** |
+
+```python
+def test_with_content(portal, create_content):
+    """Test that content is created."""
+    create_content(portal, [
+        {"type": "Document", "id": "doc1", "title": "A Document"},
+    ])
+    assert "doc1" in portal
+```
+
+### grant_roles
+
+|  |  |
+| --- | --- |
+| Description | Function to grant local roles to the test user on a given context. |
+| Required Fixture | **integration** |
+| Scope | **Session** |
+
+```python
+def test_manager_action(portal, grant_roles):
+    """Test an action that requires Manager role."""
+    grant_roles(portal, ["Manager"])
+    # test user now has Manager role on portal
+```
+
+## Markers
+
+### @pytest.mark.portal
+
+Configure the `portal` fixture with GenericSetup profiles, pre-created content, and/or user roles — without overriding the fixture.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `profiles` | `list[str]` | GenericSetup profile IDs to apply (e.g. `["my.addon:testing"]`) |
+| `content` | `list[dict]` | Dicts passed as keyword arguments to `plone.api.content.create` |
+| `roles` | `list[str]` | Roles granted to the test user via `plone.api.user.grant_roles` |
+
+Setup is applied in order: **profiles → content → roles**.
+
+```python
+import pytest
+
+
+@pytest.mark.portal(
+    profiles=["my.addon:testing"],
+    content=[{"type": "Document", "id": "doc1", "title": "Doc 1"}],
+    roles=["Manager"],
+)
+def test_something(portal):
+    """Test with custom portal setup."""
+    assert "doc1" in portal
+```
+
+Tests without the marker see no behavior change — fully backwards-compatible.
+
 ## Plugin Development
 
 You need a working `python` environment (system, virtualenv, pyenv, etc) version 3.8 or superior.
diff --git a/mx.ini b/mx.ini
@@ -12,9 +12,6 @@ version-overrides =
     zope.pytestlayer>=8.3
     pytest>=8.4.0
 
-; example section to use packages from git
-; [example.contenttype]
-; url = https://github.com/collective/example.contenttype.git
-; pushurl = git@github.com:collective/example.contenttype.git
-; extras = test
-; branch = feature-7
+[plone-stubs]
+url = https://github.com/plone/plone-stubs.git
+pushurl = git@github.com:plone/plone-stubs.git
diff --git a/news/+apply_profiles.feature b/news/+apply_profiles.feature
@@ -0,0 +1 @@
+Added `apply_profiles` session-scoped fixture to apply GenericSetup profiles to a Plone site. @ericof
diff --git a/news/+create_content.feature b/news/+create_content.feature
@@ -0,0 +1 @@
+Added `create_content` session-scoped fixture to create content items in a Plone site as the site owner. @ericof
diff --git a/news/+grant_roles.feature b/news/+grant_roles.feature
@@ -0,0 +1 @@
+Added `grant_roles` session-scoped fixture to grant local roles to the test user on a given context. @ericof
diff --git a/news/+housekeeping.internal b/news/+housekeeping.internal
@@ -0,0 +1 @@
+Updated development tooling: bumped Plone version to 6.1.4, added plone-stubs to test dependencies, updated mx.ini and .gitignore. @ericof
diff --git a/news/37.feature b/news/37.feature
@@ -0,0 +1 @@
+Added `@pytest.mark.portal` marker support for configuring the `portal` fixture with GenericSetup profiles, pre-created content, and user roles. @ericof
diff --git a/pyproject.toml b/pyproject.toml
@@ -46,6 +46,7 @@ dependencies = [
 
 [project.optional-dependencies]
 test = [
+    "plone-stubs",
     "pytest-cov",
     "pytest-xdist",
     "mypy>=1.15.0",
diff --git a/src/pytest_plone/_types.py b/src/pytest_plone/_types.py
@@ -3,6 +3,7 @@
 from plone.app.vocabularies import SlicableVocabulary
 from plone.dexterity.content import DexterityContent
 from plone.dexterity.fti import DexterityFTI
+from Products.CMFPlone.Portal import PloneSite
 from typing import Protocol
 from typing import TypeAlias
 from zope.schema.vocabulary import SimpleVocabulary
@@ -30,3 +31,17 @@ def __call__(self, name: str) -> list[str]: ...
 
 class VocabularyGetter(Protocol):
     def __call__(self, name: str, context: Context) -> PloneVocabulary: ...
+
+
+class ProfilesApplier(Protocol):
+    def __call__(self, portal: PloneSite, profiles: list[str]) -> None: ...
+
+
+class ContentCreator(Protocol):
+    def __call__(
+        self, container: DexterityContent | Item, content: list[dict]
+    ) -> None: ...
+
+
+class RolesGranter(Protocol):
+    def __call__(self, context: DexterityContent | Item, roles: list[str]) -> None: ...
diff --git a/src/pytest_plone/fixtures/__init__.py b/src/pytest_plone/fixtures/__init__.py
@@ -1,5 +1,6 @@
 """Fixtures provided by pytest-plone."""
 
+from .addons import apply_profiles
 from .addons import browser_layers
 from .addons import controlpanel_actions
 from .addons import installer
@@ -8,23 +9,39 @@
 from .base import app
 from .base import http_request
 from .base import portal
+from .content import create_content
 from .content import get_behaviors
 from .content import get_fti
 from .env import generate_mo
+from .security import grant_roles
 from .vocabularies import get_vocabulary
 
+import pytest
+
 
 __all__ = [
     "app",
+    "apply_profiles",
     "browser_layers",
     "controlpanel_actions",
+    "create_content",
     "generate_mo",
     "get_behaviors",
     "get_fti",
     "get_vocabulary",
+    "grant_roles",
     "http_request",
     "installer",
     "portal",
     "profile_last_version",
     "setup_tool",
 ]
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line(
+        "markers",
+        "portal(profiles=None, content=None, roles=None): "
+        "configure the portal fixture with GenericSetup profiles, "
+        "pre-created content, and/or user roles",
+    )
diff --git a/src/pytest_plone/fixtures/addons.py b/src/pytest_plone/fixtures/addons.py
@@ -7,6 +7,7 @@
 from Products.CMFPlone.Portal import PloneSite
 from Products.GenericSetup.tool import SetupTool
 from pytest_plone import _types as t
+from pytest_plone.fixtures import markers
 from zope.interface.interface import InterfaceClass
 
 import pytest
@@ -95,3 +96,20 @@ def profile_last_version(profile: str) -> str:
         return version[0] if version else ""
 
     return profile_last_version
+
+
+@pytest.fixture(scope="session")
+def apply_profiles() -> t.ProfilesApplier:
+    """Apply GenericSetup profiles to a Plone site.
+
+    Example usage:
+    ```python
+    def test_with_profile(portal, apply_profiles):
+        apply_profiles(portal, ["my.addon:testing"])
+    ```
+    """
+
+    def func(portal: PloneSite, profiles: list[str]) -> None:
+        markers.apply_profiles(portal, profiles)
+
+    return func
diff --git a/src/pytest_plone/fixtures/base.py b/src/pytest_plone/fixtures/base.py
@@ -1,5 +1,6 @@
 """Base fixtures."""
 
+from .markers import apply_portal_marker
 from OFS.Application import Application
 from plone.testing.layer import Layer
 from Products.CMFPlone.Portal import PloneSite
@@ -22,16 +23,29 @@ def test_app(self, app):
 
 
 @pytest.fixture()
-def portal(integration: Layer) -> PloneSite:
+def portal(integration: Layer, request: pytest.FixtureRequest) -> PloneSite:
     """Returns the default Plone Site for an integration Layer.
 
+    Supports ``@pytest.mark.portal`` to apply GenericSetup profiles,
+    create content, and grant roles before the test runs.
+
     Example usage:
     ```python
     def test_portal(self, portal):
         assert portal.title == "Plone site"
+
+    @pytest.mark.portal(
+        profiles=["my.addon:testing"],
+        content=[{"type": "Document", "id": "doc1", "title": "A document"}],
+        roles=["Manager"],
+    )
+    def test_portal_with_marker(self, portal):
+        assert "doc1" in portal
     ```
     """
-    return integration["portal"]
+    portal: PloneSite = integration["portal"]
+    apply_portal_marker(portal, request)
+    return portal
 
 
 @pytest.fixture
diff --git a/src/pytest_plone/fixtures/content.py b/src/pytest_plone/fixtures/content.py
@@ -2,8 +2,10 @@
 
 from plone.dexterity.fti import DexterityFTI
 from plone.dexterity.interfaces import IDexterityFTI
+from Products.CMFCore.PortalContent import PortalContent
 from Products.CMFPlone.Portal import PloneSite
 from pytest_plone import _types as t
+from pytest_plone.fixtures import markers
 from zope.component import queryUtility
 
 import pytest
@@ -47,3 +49,23 @@ def get_behaviors(name: str) -> list[str]:
         return list(fti.behaviors)
 
     return get_behaviors
+
+
+@pytest.fixture(scope="session")
+def create_content() -> t.ContentCreator:
+    """Create content items in a Plone site as the site owner.
+
+    Example usage:
+    ```python
+    def test_with_content(portal, create_content):
+        create_content(portal, [
+            {"type": "Document", "id": "doc1", "title": "A Document"},
+        ])
+        assert "doc1" in portal
+    ```
+    """
+
+    def func(container: PortalContent, content: list[dict]) -> None:
+        markers.create_content(container, content)
+
+    return func
diff --git a/src/pytest_plone/fixtures/markers.py b/src/pytest_plone/fixtures/markers.py
@@ -0,0 +1,61 @@
+"""Marker support for pytest-plone fixtures."""
+
+from plone import api
+from plone.app.testing import SITE_OWNER_NAME
+from plone.app.testing import TEST_USER_ID
+from Products.CMFCore.PortalContent import PortalContent
+from Products.CMFPlone.Portal import PloneSite
+from zope.component.hooks import site
+
+import pytest
+
+
+PORTAL_MARKER_NAME: str = "portal"
+
+
+def apply_profiles(portal: PloneSite, profiles: list[str]) -> None:
+    """Apply GenericSetup profiles to a Plone site.
+
+    Each entry can be either ``"my.addon:default"`` or the full
+    ``"profile-my.addon:default"`` form — the ``profile-`` prefix
+    is added automatically when missing.
+    """
+    with site(portal):
+        setup_tool = api.portal.get_tool("portal_setup")
+        for profile_id in profiles:
+            if not profile_id.startswith("profile-"):
+                profile_id = f"profile-{profile_id}"
+            setup_tool.runAllImportStepsFromProfile(profile_id)
+
+
+def create_content(container: PortalContent, content: list[dict]) -> None:
+    """Create content items in a container.
+
+    Each dict in *content* is passed as keyword arguments to
+    ``plone.api.content.create(container=container, **spec)``.
+    """
+    for spec in content:
+        api.content.create(container=container, **spec)
+
+
+def grant_roles(context: PortalContent, roles: list[str]) -> None:
+    """Grant roles to the default test user."""
+    api.user.grant_roles(username=TEST_USER_ID, roles=roles, obj=context)
+
+
+def apply_portal_marker(portal: PloneSite, request: pytest.FixtureRequest) -> None:
+    """Read ``@pytest.mark.portal`` and apply profiles, content, and roles."""
+    marker = request.node.get_closest_marker(PORTAL_MARKER_NAME)
+    if marker is None:
+        return
+    marker_profiles: list[str] = marker.kwargs.get("profiles", [])
+    marker_content: list[dict] = marker.kwargs.get("content", [])
+    marker_roles: list[str] = marker.kwargs.get("roles", [])
+    with site(portal):
+        if marker_profiles:
+            apply_profiles(portal, marker_profiles)
+        if marker_content:
+            with api.env.adopt_user(SITE_OWNER_NAME):
+                create_content(portal, marker_content)
+        if marker_roles:
+            grant_roles(portal, marker_roles)
diff --git a/src/pytest_plone/fixtures/security.py b/src/pytest_plone/fixtures/security.py
diff --git a/tests/conftest.py b/tests/conftest.py
diff --git a/tests/fixtures/test_marker_portal.py b/tests/fixtures/test_marker_portal.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Added `apply_profiles` session-scoped fixture to apply GenericSetup profiles to a Plone site. @ericof
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Added `create_content` session-scoped fixture to create content items in a Plone site as the site owner. @ericof
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Added `grant_roles` session-scoped fixture to grant local roles to the test user on a given context. @ericof
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Updated development tooling: bumped Plone version to 6.1.4, added plone-stubs to test dependencies, updated mx.ini and .gitignore. @ericof`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Added `@pytest.mark.portal` marker support for configuring the `portal` fixture with GenericSetup profiles, pre-created content, and user roles. @ericof