Actors¶
Actors are the do-ers in the screenplay. Actors set the scene, perform their hearts out, and then make dramatic assertions that will either see a happy ending or a tragic failure.
More seriously, the actors represent the users of your application, doing the things you’d expect them to do on it (or things you might not expect them to do). Screenplay Pattern focuses entirely on what your users hope to do on your site, so your test cases will focus on what the actors do, which includes gaining Abilities, performing Actions, and asking Questions.
Using Actors¶
To instantiate a new actor, just give it a name:
from screenpy.actor import Actor, AnActor
Perry = AnActor.named("Perry")
Without any abilities, your actor will be woefully unprepared to begin their performance. To give your actor an ability, you can do something like:
from selenium.webdriver import Firefox
from screenpy.abilities import BrowseTheWeb
Perry.can(BrowseTheWeb.using(Firefox()))
# For convenience, you can also do the same like this
Perry = AnActor.named("Perry").who_can(BrowseTheWeb.using(Firefox()))
Now, Perry is able to attempt any actions that require the ability to BrowseTheWeb. Attempting actions looks like this:
from screenpy import Target
from screenpy.actions import Click
EXAMPLE_LINK = Target.the("example link").located_by("//a")
Perry.attempts_to(Click.the(EXAMPLE_LINK))
You’ll notice we had to make a quick Target there.
We’ll get to Targets later,
but a quick summary
is that they’re how you tell the actors
where to perform the action.
In the above example,
the action knows
what ability it requires,
and it will ask the actor
to find its matching ability
to perform the action.
If the actor
does not have that ability,
the actor will raise an UnableToPerformError.
Now that our actor has performed an action, they are ready to perform a test. Tests are performed with Questions, like so:
from screenpy.questions import Text
from screenpy.resolutions import ReadsExactly
THE_WELCOME_MESSAGE = Target.the("welcome_message").located_by("span.welcome")
Perry.should_see_the((Text.of(THE_WELCOME_MESSAGE), ReadsExactly("Welcome!"))
That’s the whole flow! Your actor is now ready to exit:
Perry.exits_stage_right()
Actor Class¶
-
class
screenpy.actor.Actor(name: str)¶ Represents an actor, holding their name and abilities. Actors are the performers of your screenplay, they represent your users as they go about their business on your product.
An actor is meant to be instantiated using its static
named()method. A typical invocation might look like:Perry = Actor.named(“Perry”)This will create the actor, ready to take on their first role.
-
ability_to(ability: Any) → Any¶ Syntactic sugar for
uses_ability_to().
-
attempts_to(*actions) → None¶ Performs a list of actions, one after the other.
Parameters: actions – the list of actions to perform.
-
exit() → None¶ The actor forgets all of their abilities, ready to assume a new role when their next cue calls them.
-
static
named(name: str) → screenpy.actor.Actor¶ Names this actor, logs their entrance, and returns the instance.
Parameters: name – the name of this new Actor. Returns: Actor
-
should_see(*tests) → None¶ Syntactic sugar for
should_see_the().
-
should_see_that(*tests) → None¶ Syntactic sugar for
should_see_the().
-
should_see_the(*tests) → None¶ Asks a series of questions, asserting that the expected answer resolves.
Parameters: tests – tuples of a Questions and a Resolutions. Raises: AssertionError– If the question’s actual answer does not match the expected answer from the Resolutions.
-
uses_ability_to(ability: Any) → Any¶ Finds the ability referenced and returns it, if the actor is able to do it.
Parameters: ability – the ability to retrieve. Returns: The requested ability. Raises: |UnableToPerformError|– the actor doesn’t possess the ability.
-
was_able_to(*actions) → None¶ Syntactic sugar for
attempts_to().
-