Protocols

These are the protocols followed by ScreenPy. They form the basis of the structural subtyping employed by ScreenPy.

Each class type below must follow the listed protocol to be considered that class type.

Ability

class Forgettable(*args, **kwargs)

Abilities are Forgettable.

forget() → None

Clean up the Ability, assuming it will not be used again.

This may involve closing database connections, quitting browsers, deleting data from an API, etc.

Action

class Performable(*args, **kwargs)

Actions and Tasks are Performable.

perform_as(the_actor: Actor) → None

Direct the Actor to perform this Action.

Args:

the_actor: the Actor who will perform this Action.

Question

class Answerable(*args, **kwargs)

Questions are Answerable.

answered_by(the_actor: Actor) → Any

Pose the Question to the Actor, who will attempt to answer.

Args:

the_actor: the Actor who will answer this Question.

Returns:

The answer, based on the sleuthing the Actor has done.

Resolution

class Resolvable(*args, **kwargs)

Resolutions are Resolvable.

resolve() → Matcher

Form the Matcher for an assertion.

Returns:

Matcher: the Matcher this Resolution uses for the expected value.

Narrator’s Adapter

class Adapter(*args, **kwargs)

Required functions for an adapter to the Narrator’s microphone.

Adapters allow the Narrator’s microphone to broadcast to multiple reporting tools, such as stdout or Allure.

Each of the methods described below correspond to the screenpy.pacing decorators of the same name. The Narrator expects each of these methods to yield the function back. This allows each adapter to modify the function in whatever ways it needs to while allowing the adapters before and after to do the same.

Adapters must follow the function signatures exactly, even if the adapter does not use one or more of the parameters. The Narrator passes these arguments in as keyword arguments, so they must not be renamed.

act(func: Callable, line: str, gravitas: str | None = None) → Generator

Handle narrating an Act, which designates a group of tests.

scene(func: Callable, line: str, gravitas: str | None = None) → Generator

Handle narrating a Scene, which designates a subgroup of tests.

beat(func: Callable, line: str, gravitas: str | None = None) → Generator

Handle narrating a Beat, which is a step in a test.

aside(func: Callable, line: str, gravitas: str | None = None) → Generator

Handle narrating an Aside, which can happen any time.

error(exc: Exception) → None

React to an exception being thrown, probably during a beat.

attach(filepath: str, **kwargs: Any) → None

Handle attaching a file.

Pass keyword arguments for specific adapters’ needs.