As an acceptance-test suite grows, steps that mix business intent with browser calls, selectors, URLs, and waits become hard to reuse and maintain. The Screenplay pattern separates what a user is trying to achieve from how the system is operated. Tests describe actors pursuing goals through reusable activities, rather than organizing behavior around pages or large action classes. section 10.4 section 12.1
Five elements work together:
- Actors represent users or external systems. An actor can perform activities and check results; separate actors can take different roles in one workflow. section 12.2 section 12.1
- Abilities give actors access to interfaces, such as a browser or API. Interactions are reusable objects describing basic actions, such as clicking a button or sending a request. section 12.11 section 12.5.2
- Tasks combine interactions or other tasks into business activities. Questions retrieve system state so assertions can check expected behavior. section 12.2 section 12.9.2
Keep scenario steps business-readable. A step such as registering for an account can delegate to tasks for navigating, entering details, and confirming terms; those tasks delegate to lower-level interactions. This lets a workflow change without putting button clicks and field names into the scenario step. Even a one-interaction task can give a shared URL or selector one place to live and produce a more meaningful execution report. section 9.3.2 section 12.9.1
public class SearchFlights {
public static Performable matching(FlightSearch searchCriteria) {
return Task.where("Search for matching flights", #1
Navigate.toBookFlights(), #2
Type.theValue(searchCriteria.from()) #3
.into(SearchFlightsForm.FROM),
Type.theValue(searchCriteria.to()) #4
.into(SearchFlightsForm.TO),
Select.option(searchCriteria.travelClassName()) #5
.from(SearchFlightsForm.TRAVEL_CLASS_DROPDOWN),
Click.on(SearchFlightsForm.SEARCH_BUTTON), #6
WaitUntil.the(SearchResultsList.SEARCH_RESULTS,isVisible())
.forNoMoreThan(5).seconds() #7
);
}
}
A flight-search task composes navigation, form entry, a click, and a wait behind one business-named activity. Its caller need only ask the actor to search for matching flights. section 12.1
From scenario to assertion
A Cucumber step can receive an actor and ask them to sign up using traveler details. A later step can retrieve the current actor and check account status against expected values from a scenario table. In a two-person workflow, distinct actors can perform and verify their own activities rather than sharing an implicit user. section 14.3 section 12.10.5 section 12.1
Screenplay is a design pattern, not a screen-only library: the same actor-centered structure can drive UI and REST interactions. Serenity BDD and Serenity/JS provide implementations; in Cucumber, a Cast configures actors and OnStage manages them between steps. The payoff is test code that can express business flows at a high level while retaining inspectable interactions underneath. section 12.3 section 12.5.4 section 12.11
