Actions API

These are the Actions included in ScreenPy.

AttachTheFile

Aliases: AttachAFile, AttachFile, AttachesTheFile, AttachesAFile, AttachesFile

class AttachTheFile(filepath: str, **kwargs: Any)

Attach a file for Narration.

Supports passing arbitrary keyword arguments along to the adapters hooked up to the Narrator’s microphone.

Examples:

the_actor.attempts_to(AttachTheFile(filepath))

the_actor.attempts_to(
    AttachTheFile(filepath, attachment_type=AttachmentTypes.PNG)
)

property filename: str: Get the filename from the filepath.

Debug

class Debug

Activate a debugger to step through Actions.

In long series of Actions, it can be difficult to drop a debugger in the right place. This Action can be placed anywhere in the list to give you a debugger in the middle of the Action list. This Action uses Python 3.7+’s breakpoint() call if it can, otherwise it will default to pdb.set_trace().

Examples:

the_actor.attempts_to(
    Click.on_the(SIGN_IN_BUTTON),
    # ...
    Debug(),
    Wait.for_the(SURPRISE_CONFETTI).to_disappear(),
    # ...
)

Eventually

class Eventually(performable: Performable)

Retry a performable that will eventually (hopefully) succeed.

Eventually ignores all errors for the duration of its attempt. If the Actor is not able to complete the given Action or Task within the timeout period, a DeliveryError is raised (from the last caught exception).

Examples:

the_actor.should(
    Eventually(
        See.the(Text.of_the(WELCOME_BANNER), ContainsTheText("Welcome!"))
    ),
)

the_actor.attempts_to(
    Eventually(Click.on_the(BUTTON)).trying_every(100).milliseconds()
)

the_actor.was_able_to(
    Eventually(DismissAlert())
    .trying_for(5)
    .seconds()
    .polling_every(500)
    .milliseconds(),
)

for_(amount: float) → _TimeframeBuilder

Set for how long the actor should continue trying.

Aliases:

trying_for_no_longer_than()
trying_for()
waiting_for()

trying_for_no_longer_than(amount: float) → _TimeframeBuilder: Alias for for_().

trying_for(amount: float) → _TimeframeBuilder: Alias for for_().

waiting_for(amount: float) → _TimeframeBuilder: Alias for for_().

polling(amount: float) → _TimeframeBuilder

Adjust the polling frequency.

Aliases:

polling_every()
trying_every()

polling_every(amount: float) → _TimeframeBuilder: Alias for polling().

trying_every(amount: float) → _TimeframeBuilder: Alias for polling().

property performable_to_log: str: Represent the Performable in a log-friendly way.

Log

class Log(question: T_Q)

Log the answer to a Question, or anything.

Probably most useful for debugging a test, or for announcing the answer to a Question for the record.

Examples::

the_actor.attempts_to(Log(HowManyBirdsAreInTheSky()))

the_actor.attempts_to(Log.the(Number.of(SNAKES_ON_THE_PLANE)))

classmethod the(question: T_Q) → Self: Supply the Question to answer.

property question_to_log: str: Represent the Question in a log-friendly way.

MakeNote

Aliases: TakeNote, MakesNote, TakesNote

class MakeNote(question: T_Q, key: str | None = None)

Make a note of a value or the answer to a Question.

You can access noted values with Included Directions at any point during a test, except immediately after making the note. See https://screenpy-docs.readthedocs.io/en/latest/cookbook.html#using-makenote.

Examples:

the_actor.attempts_to(
    MakeNote.of_the(Number.of(BALLOONS)).as_("excitement gauge"),
)

the_actor.attempts_to(MakeNote.of_the(items).as_("items list"))

classmethod of(question: T_Q) → Self

Supply the Question to answer and its arguments.

Aliases:

of_the()

classmethod of_the(question: T_Q) → Self: Alias for of().

as_(key: str) → Self: Set the key to use to recall this noted value.

property key_to_log: str | None: Represent the key in a log-friendly way.

Pause

Aliases: Sleep, Pauses, Sleeps

class Pause(number: float)

Pause the Actor’s Actions for a set amount of time.

This class should only be used when absolutely necessary. Hard waits are the worst of all wait strategies; providing a reason will help explain why pausing is necessary. You must call one of the “…_because” methods to pass a reason for pausing. An UnableToAct exception will be raised if no reason was given.

Examples:

the_actor.attempts_to(
    Pause.for_(10).seconds_because("they're being dramatic.")
)

the_actor.attempts_to(
    Pause.for_(500).milliseconds_because("of a moment's hesitation.")
)

classmethod for_(number: float) → Self: Specify how many seconds or milliseconds to wait for.

seconds_because(reason: str) → Self

Use seconds and provide a reason for the pause.

Aliases:

second_because()

second_because(reason: str) → Self: Alias for seconds_because().

milliseconds_because(reason: str) → Self: Use milliseconds and provide a reason for the pause.

See

Aliases: Assert, Confirm, Observe, Verify, Sees, Asserts, Confirms, Observes, Verifies

class See(question: T_Q, resolution: T_R)

See if a value or the answer to a Question matches the Resolution.

This is a very important Action in ScreenPy; it is the way to perform test assertions. For more information, see the documentation for Questions and Resolutions.

Examples:

the_actor.should(
    See(TheText.of_the(WELCOME_MESSAGE), ReadsExactly("Welcome!")),
)

the_actor.should(
    See.the(list_of_items, ContainsTheItem("juice extractor")),
)

classmethod the(question: T_Q, resolution: T_R) → Self: Supply the Question (or value) and Resolution to test.

property question_to_log: str: Represent the Question in a log-friendly way.

property resolution_to_log: str: Represent the Resolution in a log-friendly way.

SeeAllOf

Aliases: AssertAllOf, ConfirmAllOf, ObserveAllOf, VerifyAllOf, SeesAllOf, AssertsAllOf, ConfirmsAllOf, ObservesAllOf, VerifiesAllOf

class SeeAllOf(*tests: T_T)

See if all the provided values or Questions match their Resolutions.

Uses See to assert all values or the answers to the Questions match their paired Resolutions:.

Examples:

the_actor.should(
    SeeAllOf(
        (TheText.of_the(WELCOME_MESSAGE), ReadsExactly("Welcome!")),
        (the_character_speech_bubble, ContainsTheText("Howdy!")),
    )
)

the_actor.should(
    SeeAllOf.the(
        (Number.of(BALLOONS), IsEqualTo(3)),
    )
)

classmethod the(*tests: T_T) → Self: Supply any number of Question/value + Resolution tuples to test.

SeeAnyOf

Aliases: AssertAnyOf, ConfirmAnyOf, ObserveAnyOf, VerifyAnyOf, SeesAnyOf, AssertsAnyOf, ConfirmsAnyOf, ObservesAnyOf, VerifiesAnyOf

class SeeAnyOf(*tests: T_T)

See if at least one value or Question matches its Resolution.

Uses See to assert at least one of the values or the answers to the Questions match their paired Resolutions:.

Examples:

the_actor.should(
    SeeAnyOf(
        (TheText.of_the(WELCOME_MESSAGE), ReadsExactly("Welcome!")),
        (the_character_speech_bubble, ContainsTheText("Howdy!")),
    )
)

the_actor.should(
    SeeAnyOf.the(
        (Number.of(BALLOONS), IsEqualTo(4)),
    )
)

classmethod the(*tests: T_T) → Self: Supply any number of Question/value + Resolution tuples to test.

Silently

Aliases: Quietly

Silently(duck: T) → T

Silence the duck.

Any Performable, Answerable, or Resolvable wrapped in Silently will not be narrated by the Narrator, unless an exception is raised.

Args:: duck: Performable, Answerable, or Resolvable
Returns:: Performable, Answerable, or Resolvable

Examples:

the_actor.will(Silently(Click.on(THE_BUTTON)))

the_actor.shall(
    See(
        Silently(Text.of_the(WELCOME_BANNER)), ContainsTheText("Welcome!")
    )
)

the_actor.shall(
    See(
        Text.of_the(WELCOME_BANNER), Silently(ContainsTheText("Welcome!"))
    )
)

Either

Aliases: Attempt, AttemptTo, GoFor, Try TryTo, Attempts, AttemptsTo, GoesFor, Tries, TriesTo

class Either(*first: Performable)

Perform one of two branching performances.

Simulates a try/except block while still following Screenplay Pattern.

By default, Either catches AssertionErrors, so you can use See to decide which path to follow. Use the ignoring() method to ignore other exceptions.

Examples:

the_actor.will(Either(DoAction()).or_(DoDifferentAction())

the_actor.will(
    Either(DoAction()).otherwise(DoDifferentAction()).ignoring(
        AssertionError, NotImplementedError
    )
)

# using a custom Task which raises AssertionError
the_actor.will(
    Either(CheckIfOnDomain(URL())).or_(Open.their_browser_on(URL())
)