Narration

Telling the story of your actors’ screenplay falls to the Narrator. The Narrator is responsible for describing the scene, marking the tests, and attaching files.

You can fit the Narrator’s microphone with adapters to send the thrilling account to different reporting tools. The default Adapter provided with ScreenPy logs to stdout. There may be more Adapters available in the Official Extensions section.

Describing Your Tests and Tasks

ScreenPy uses decorators to categorize tests and narrate actions.

act and scene

These two decorators can be used to categorize tests. Use them in any way that makes sense for your team, but act is usually meant for designating suite-level organization, while scene is meant for smaller groupings.

beat

A beat marks and describes an Action your Actor is performing or a Question your Actor is asking. In other words, it marks a test step.

Performables and Answerables might reference other Performables and Answerables in their execution.

aside

Asides speak a line directly to the adapters. Use these to add a quick comment to the report.

Built-In StdOutAdapter

The default StdOutAdapter logs its narration to stdout. You can see the full output by following the instructions for the ReadTheDocs example in the ScreenPy Examples collection, but here’s just the output from the test_dramatic_moment test in the Complete Example:

features/test_mood.py::test_dramatic_moment
----- live log setup -----
INFO     screenpy:stdout_adapter.py:42 Cameron arrives on stage!
INFO     screenpy:stdout_adapter.py:42 Polly gets over their stagefright!
----- live log call -----
INFO     screenpy:stdout_adapter.py:42 Cameron starts recording on Will.
INFO     screenpy:stdout_adapter.py:42 Cameron skips to scene #35.
INFO     screenpy:stdout_adapter.py:42 Cameron dollies the active camera left.
INFO     screenpy:stdout_adapter.py:42 Cameron cuts to a closeup on Will!
INFO     screenpy:stdout_adapter.py:42     Cameron zooms in.
INFO     screenpy:stdout_adapter.py:42     Cameron jumps to the camera on Will!
INFO     screenpy:stdout_adapter.py:42 Cameron executes a dramatic dolly zoom!
INFO     screenpy:stdout_adapter.py:42     Cameron performs some thrilling camerawork simultaneously!
INFO     screenpy:stdout_adapter.py:42         Cameron dollies the active camera backward.
INFO     screenpy:stdout_adapter.py:42         Cameron zooms in.
INFO     screenpy:stdout_adapter.py:42 Polly sees if audience tension is a palpable tension!.
INFO     screenpy:stdout_adapter.py:42     ... hoping it's a palpable tension!
INFO     screenpy:stdout_adapter.py:42         => True
PASSED
----- live log teardown -----
INFO     screenpy:stdout_adapter.py:42 Cameron stops recording.

The above is what logging looks like when using pytest along with the --log-cli-level=info option.

Using Adapters

To include Adapters on the Narrator’s microphone, do this:

from screenpy import StdOutAdapter, the_narrator

the_narrator.attach_adapter(StdOutAdapter())

Do the above in conftest.py or a similar setup file to set the Adapters for your test suite. You are able to add any number of Adapters in any order.

Creating New Adapters

The Adapter protocol describes what an adapter looks like.

The function signatures must remain completely intact. The new adapter’s methods must also yield back a function for act, scene, beat, and aside. Most likely this will be the function passed to it in the first place, having been modified in some way.

The attach function allows the narrator to attach a file. Each adapter will handle this differently. The signature only has one required argument: the filepath. This argument is a string, and may or may not be a filepath, depending on what reporting tool the new adapter supports. Pass any other required arguments as keyword arguments, so the other adapters can ignore them.