attic.rst

Overview

This file provides an instructional example of how to configure and implement acceptance tests using the pytest framework. It demonstrates defining custom command-line options, creating fixture factories (funcargs) for acceptance testing, and how to decorate these fixtures at different scopes (global `conftest.py` and per-test-module) to customize test behavior.

The primary purpose of this file is to guide users on enabling, running, and structuring acceptance tests that may be slower or more complex than typical unit tests. It illustrates how to skip tests unless a specific command line flag (`-A`) is set, how to create temporary directories for test isolation, and how to run subprocess commands as part of acceptance tests.

This documentation covers the example code snippets, explains the fixture design, and describes how they interact with pytest’s plugin and fixture systems.

Detailed Explanation

pytest_option(parser)

• Purpose:
  Defines a new command-line option for pytest allowing users to selectively run acceptance tests.

• Parameters:

  • parser: The pytest parser object used to add command-line options.

• Functionality:
  Adds an option group named "myproject" and registers a boolean flag -A with destination acceptance. When specified, this flag enables acceptance tests.

• Usage:
  Run pytest with -A to enable acceptance tests:

  pytest -A
  

pytest_funcarg__accept(request)

• Purpose:
  A pytest “funcarg factory” that returns an instance of AcceptFixture for use in acceptance tests.

• Parameters:

  • request: The pytest request object providing test context and configuration.

• Returns:

  • An instance of the AcceptFixture class, which encapsulates acceptance test support functionality.

• Usage:
  This factory makes the accept fixture available to test functions. For example:

  def test_example(accept):
      # use accept fixture
  

class AcceptFixture

`AcceptFixture` provides helper methods and environment control for acceptance tests.

__init__(self, request)

• Parameters:

  • request: The pytest request object providing access to configuration and test metadata.

• Behavior:

  • Checks if the -A acceptance flag is set; if not, skips the test with an informative message.

  • Creates a temporary directory specific to the test function using pytest’s mktemp method.

• Usage:
  Automatically invoked when the accept fixture is requested.

run(self, *cmd)

• Parameters:

  • *cmd: A variable-length argument list representing the command and its arguments to be executed as a subprocess.

• Returns:

  • The decoded string output (stdout) of the executed command.

• Functionality:

  • Changes the current working directory to the fixture’s temporary directory.

  • Executes the given command using subprocess.check_output.

  • Decodes and returns the output for assertions.

• Usage example:

  result = accept.run("ls", "-la")
  assert "somesub" in result
  

Example acceptance test function

def test_some_acceptance_aspect(accept):
    accept.tmpdir.mkdir("somesub")
    result = accept.run("ls", "-la")
    assert "somesub" in result

• Demonstrates using the accept fixture to create a subdirectory and verify it appears in the output of an ls command.

• Will be skipped unless pytest is invoked with -A.

Decorating a funcarg in a test module

• Shows how to locally override or extend the accept fixture in a test module.

def pytest_funcarg__accept(request):
    # Retrieve the original accept fixture
    arg = request.getfuncargvalue("accept")
    # Add a special directory for this test module
    arg.tmpdir.mkdir("special")
    return arg


class TestSpecialAcceptance:
    def test_sometest(self, accept):
        assert accept.tmpdir.join("special").check()

• The module-level pytest_funcarg__accept calls the base fixture factory and adds extra setup.

• Provides a flexible way to customize fixtures on a per-module basis without modifying the global conftest.py.

• Useful for large projects needing specialized acceptance test environments.

Implementation Details and Algorithms

• Uses pytest’s hook system for adding options (pytest_option) and creating fixtures (pytest_funcarg__accept).

• Acceptance tests are conditionally skipped to avoid running slow tests unless explicitly requested.

• Temporary directories are created per test function using mktemp to isolate test artifacts.

• Commands run in acceptance tests are executed in subprocesses with controlled working directories.

• The fixture decoration pattern leverages pytest’s ability to chain fixture factories, enabling composable setup.

Interactions with Other System Components

• pytest framework:
  The examples rely heavily on pytest’s plugin and fixture architecture, including command-line options, fixture factories, and test skipping.

• conftest.py:
  The base fixture (AcceptFixture) and command-line option are typically defined in a conftest.py plugin file to apply project-wide.

• Test modules:
  Individual test modules can decorate or extend the base accept fixture to add module-specific setup.

• py.path.local:
  The temporary directory object (tmpdir) is a py.path.local instance, providing convenient file system methods.

• subprocess module:
  Acceptance commands are executed using subprocess.check_output to capture output for verification.

Visual Diagram

classDiagram
    class AcceptFixture {
        -tmpdir: py.path.local
        +__init__(request)
        +run(*cmd): str
    }

    pytest_funcarg__accept() --> AcceptFixture
    pytest_option(parser)
    test_some_acceptance_aspect(accept)
    pytest_funcarg__accept (module-level) --> AcceptFixture
    pytest_funcarg__accept (module-level) --> pytest_funcarg__accept (conftest)

• The diagram shows the central AcceptFixture class with its properties and methods.

• The pytest_funcarg__accept factory creates AcceptFixture instances.

• The module-level pytest_funcarg__accept decorates the base factory.

• The test function consumes the accept fixture.

• The pytest_option function adds the command-line option to enable acceptance tests.

Summary

This file serves as a practical example of extending pytest with acceptance testing capabilities. It covers:

• Defining custom CLI options to control test execution.

• Creating reusable, configurable fixtures for acceptance test environments.

• Using pytest’s fixture decoration for modular and layered test setup.

• Running subprocess commands within isolated temporary directories.

• Skipping tests conditionally based on user input.

Together, these patterns help maintain a clean separation between fast unit tests and slower acceptance tests, improving test suite performance and manageability.

**End of attic.rst documentation**