feat!(test): add a pytest plugin

craft_application/pytest_plugin.py

@@ -0,0 +1,145 @@
+# Copyright 2025 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License version 3, as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License along
+# with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""A pytest plugin for assisting in testing apps that use craft-application."""
+
+from __future__ import annotations
+
+import os
+import pathlib
+import platform
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
+
+import craft_platforms
+import pytest
+
+from craft_application import util
+from craft_application.util import platforms
+
+if TYPE_CHECKING:
+    from pyfakefs.fake_filesystem import FakeFilesystem
+
+
+@pytest.fixture(autouse=True, scope="session")
+def debug_mode() -> None:
+    """Ensure that the application is in debug mode, raising exceptions from run().
+
+    This fixture is automatically used. To disable debug mode for specific tests that
+    require it, use the :py:func:`production_mode` fixture.
+    """
+    os.environ["CRAFT_DEBUG"] = "1"
+
+
+@pytest.fixture
+def production_mode(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Put the application into production mode.
+
+    This fixture puts the application into production mode rather than debug mode.
+    It should only be used if the application needs to test behaviour that differs
+    between debug mode and production mode.
+    """
+    monkeypatch.setenv("CRAFT_DEBUG", "0")
+
+
+@pytest.fixture
+def managed_mode(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Tell the application it's running in managed mode.
+
+    This fixture sets up the application's environment so that it appears to be using
+    managed mode. Useful for testing behaviours that only occur in managed mode.
+    """
+    if os.getenv("CRAFT_BUILD_ENVIRONMENT") == "host":
+        raise LookupError("Managed mode and destructive mode are mutually exclusive.")
+    monkeypatch.setenv(platforms.ENVIRONMENT_CRAFT_MANAGED_MODE, "1")
+
+
+@pytest.fixture
+def destructive_mode(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Tell the application it's running in destructive mode.
+
+    This fixture sets up the application's environment so that it appears to be running
+    in destructive mode with the "CRAFT_BUILD_ENVIRONMENT" environment variable set.
+    """
+    if os.getenv(platforms.ENVIRONMENT_CRAFT_MANAGED_MODE):
+        raise LookupError("Destructive mode and managed mode are mutually exclusive.")
+    monkeypatch.setenv("CRAFT_BUILD_ENVIRONMENT", "host")
+
+
+def _optional_pyfakefs(request: pytest.FixtureRequest) -> FakeFilesystem | None:
+    """Get pyfakefs if it's in use by the fixture request."""
+    if {"fs", "fs_class", "fs_module", "fs_session"} & set(request.fixturenames):
+        try:
+            from pyfakefs.fake_filesystem import FakeFilesystem
+
+            fs = request.getfixturevalue("fs")
+            if isinstance(fs, FakeFilesystem):
+                return fs
+        except ImportError:
+            # pyfakefs isn't installed,so this fixture means something else.
+            pass
+    return None
+
+
+@pytest.fixture(params=craft_platforms.DebianArchitecture)
+def fake_host_architecture(
+    request: pytest.FixtureRequest, monkeypatch: pytest.MonkeyPatch
+) -> Iterator[craft_platforms.DebianArchitecture]:
+    """Run this test as though running on each supported architecture.
+
+    This parametrized fixture provides architecture values for all supported
+    architectures, simulating as though the application is running on that architecture.
+    This fixture is limited to setting the architecture within this python process.
+    """
+    arch: craft_platforms.DebianArchitecture = request.param
+    platform_arch = arch.to_platform_arch()
+    real_uname = platform.uname()
+    monkeypatch.setattr(
+        "platform.uname", lambda: real_uname._replace(machine=platform_arch)
+    )
+    util.get_host_architecture.cache_clear()
+    yield arch
+    util.get_host_architecture.cache_clear()
+
+
+@pytest.fixture
+def project_path(request: pytest.FixtureRequest) -> pathlib.Path:
+    """Get a temporary path for a project.
+
+    This fixture creates a temporary path for a project. It does not create any files
+    in the project directory, but rather provides a pristine project directory without
+    the need to worry about other fixtures loading things.
+
+    This fixture can be used with or without pyfakefs.
+    """
+    if fs := _optional_pyfakefs(request):
+        project_path = pathlib.Path("/test/project")
+        fs.create_dir(project_path)  # type: ignore[reportUnknownMemberType]
+        return project_path
+    tmp_path: pathlib.Path = request.getfixturevalue("tmp_path")
+    path = tmp_path / "project"
+    path.mkdir()
+    return path
+
+
+@pytest.fixture
+def in_project_path(
+    project_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> pathlib.Path:
+    """Run the test inside the project path.
+
+    Changes the working directory of the test to use the project path.
+    Best to use with ``pytest.mark.usefixtures``
+    """
+    monkeypatch.chdir(project_path)
+    return project_path

docs/conf.py

@@ -39,6 +39,7 @@
 
 extensions = [
     "canonical_sphinx",
+    "sphinx.ext.autodoc",
 ]
 # endregion
 

docs/reference/changelog.rst

@@ -4,6 +4,23 @@
 Changelog
 *********
 
+5.0.0 (2025-Mon-DD)
+-------------------
+
+Testing
+=======
+
+- A new :doc:`pytest-plugin` with a fixture that enables production mode for the
+  application if a test requires it.
+
+Breaking changes
+================
+
+- The pytest plugin includes an auto-used fixture that puts the app into debug mode
+  by default for tests.
+
+For a complete list of commits, check out the `5.0.0`_ release on GitHub.
+
 4.9.1 (2025-Feb-12)
 -------------------
 
@@ -23,7 +40,7 @@ Application
 ===========
 
 - Add a feature to allow `Python plugins
-  https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/>`_
+  <https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/>`_
   to extend or modify the behaviour of applications that use craft-application as a
   framework. The plugin packages must be installed in the same virtual environment
   as the application.
@@ -588,3 +605,4 @@ For a complete list of commits, check out the `2.7.0`_ release on GitHub.
 .. _4.8.3: https://github.com/canonical/craft-application/releases/tag/4.8.3
 .. _4.9.0: https://github.com/canonical/craft-application/releases/tag/4.9.0
 .. _4.9.1: https://github.com/canonical/craft-application/releases/tag/4.9.1
+.. _5.0.0: https://github.com/canonical/craft-application/releases/tag/5.0.0

docs/reference/index.rst

@@ -9,6 +9,7 @@ Reference
    changelog
    environment-variables
    platforms
+   pytest-plugin
 
 Indices and tables
 ==================

docs/reference/pytest-plugin.rst

@@ -0,0 +1,38 @@
+.. py:module:: craft_application.pytest_plugin
+
+pytest plugin
+=============
+
+craft-application includes a `pytest`_ plugin to help ease the testing of apps that use
+it as a framework.
+
+By default, this plugin sets the application into debug mode, meaning the
+:py:meth:`~craft_application.Application.run()` method will re-raise generic exceptions.
+
+
+Fixtures
+--------
+
+.. autofunction:: production_mode
+
+.. autofunction:: managed_mode
+
+.. autofunction:: destructive_mode
+
+.. autofunction:: fake_host_architecture
+
+.. autofunction:: project_path
+
+.. autofunction:: in_project_path
+
+Auto-used fixtures
+~~~~~~~~~~~~~~~~~~
+
+Some fixtures are automatically enabled for tests, changing the default behaviour of
+applications during the testing process. This is kept to a minimum, but is done when
+the standard behaviour could cause subtle testing issues.
+
+.. autofunction:: debug_mode
+
+
+.. _pytest: https://docs.pytest.org

pyproject.toml

@@ -42,7 +42,8 @@ classifiers = [
 ]
 requires-python = ">=3.10"
 
-[project.scripts]
+[project.entry-points.pytest11]
+craft_application = "craft_application.pytest_plugin"
 
 [project.optional-dependencies]
 remote = [

tests/conftest.py

@@ -43,17 +43,6 @@
     from collections.abc import Iterator
 
 
-@pytest.fixture(autouse=True)
-def debug_mode(monkeypatch):
-    monkeypatch.setenv("CRAFT_DEBUG", "1")
-
-
-@pytest.fixture
-def production_mode(monkeypatch, debug_mode):
-    # This uses debug_mode to ensure that we run after it.
-    monkeypatch.delenv("CRAFT_DEBUG")
-
-
 def _create_fake_build_plan(num_infos: int = 1) -> list[models.BuildInfo]:
     """Create a build plan that is able to execute on the running system."""
     arch = util.get_host_architecture()

tests/integration/test_application.py

@@ -488,7 +488,7 @@ def test_lifecycle_error_logging(monkeypatch, tmp_path, create_app):
     assert parts_message in log_contents
 
 
-@pytest.mark.usefixtures("pretend_jammy", "emitter", "production_mode")
+@pytest.mark.usefixtures("pretend_jammy", "emitter")
 def test_runtime_error_logging(monkeypatch, tmp_path, create_app, mocker):
     monkeypatch.chdir(tmp_path)
     shutil.copytree(INVALID_PROJECTS_DIR / "build-error", tmp_path, dirs_exist_ok=True)
@@ -503,7 +503,8 @@ def test_runtime_error_logging(monkeypatch, tmp_path, create_app, mocker):
     monkeypatch.setattr("sys.argv", ["testcraft", "pack", "--destructive-mode"])
     app = create_app()
 
-    app.run()
+    with pytest.raises(RuntimeError):
+        app.run()
 
     log_contents = craft_cli.emit._log_filepath.read_text()
 

tests/unit/conftest.py

@@ -22,7 +22,7 @@
 import pytest
 import pytest_mock
 
-from craft_application import git, services, util
+from craft_application import git, services
 from craft_application.services import service_factory
 
 BASIC_PROJECT_YAML = """
@@ -37,12 +37,6 @@
 """
 
 
-@pytest.fixture(params=["amd64", "arm64", "riscv64"])
-def fake_host_architecture(monkeypatch, request) -> str:
-    monkeypatch.setattr(util, "get_host_architecture", lambda: request.param)
-    return request.param
-
-
 @pytest.fixture
 def provider_service(
     app_metadata, fake_project, fake_build_plan, fake_services, tmp_path
@@ -110,11 +104,8 @@ def expected_git_command(
 
 
 @pytest.fixture
-def fake_project_file(monkeypatch, tmp_path):
-    project_dir = tmp_path / "project"
-    project_dir.mkdir()
-    project_path = project_dir / "testcraft.yaml"
-    project_path.write_text(BASIC_PROJECT_YAML)
-    monkeypatch.chdir(project_dir)
-
-    return project_path
+def fake_project_file(in_project_path):
+    project_file = in_project_path / "testcraft.yaml"
+    project_file.write_text(BASIC_PROJECT_YAML)
+
+    return project_file