#screenplay pattern

This is part 3 of 3 in a series about using the Screenplay pattern in Swift.

Part 1: What is the Screenplay Pattern?

Part 2: Screenplay Entities with XCTest and Swift

In part 2, we went through a basic implementation of Screenplay pattern entities for the 'bag' domain area of an e-commerce app. In this part, we will see how those entities are used together at the test level to create functional tests.

Vanilla Screenplay Tests

In this example, we'll use the Screenplay entities created in part 2, along with an additional StartedWith task I created, to implement a test for the following scenario:

Given I have six items in my bag When I remove an item from my bag Then I will have five items in my bag

First off, we create an Actor. Your test will center around an Actor. The Actor will perform Tasks and ask Questions. You can assign your actor to a constant so that you don't have to make a new Actor every time you want to get something done.

let alice = Actor(called: "Alice")

Now that you have an Actor ready to do some work, have the Actor perform the test setup. In this scenario, there's only one setup step; having six items in the bag.

alice.has(StartedWith.sixBagItems())

StartedWith.sixBagItems() is a Task which launches the app and ensures that the user's bag has six items in it.

After the test setup is complete, it's time to perform the task which is the subject of our test; removing an item from the bag.

alice.attemptsTo(RemoveBagItem.inPosition(1))

The test scenario doesn't explicitly call for a particular item to be removed, so you can request any index from 0-5 to be removed on this line to satisfy the scenario's requirement.

Finally, ask the Actor if it can see the expected result.

alice.sees(BagItems.displayedCount(is: 5))

And voilà, you have successfully built a Screenplay test!

import XCTest class BagTests: XCTestCase { func testBagItemsCanBeRemoved() { let alice = Actor(called: "Alice") alice.has(StartedWith.sixBagItems()) alice.attemptsTo(RemoveBagItem.inPosition(1)) alice.sees(Bag.Items.displayedCount(is: 5)) } }

If you wanted to use Alice as your Actor for all of the tests in your test class, you could add her to the setUp() method.

import XCTest class BagTests: XCTestCase { var alice: Actor! override func setUp() { alice = Actor(called: "Alice") } func testBagItemsCanBeRemoved() { alice.has(StartedWith.sixBagItems()) alice.attemptsTo(RemoveBagItem.inPosition(1)) alice.sees(Bag.Items.displayedCount(is: 5)) } // More tests go here... }

That's it. Unless you want a Gherkin-like interface...

Screenplay + Given, When, Then

If the 'vanilla' screenplay test style shown above isn't Gherkin-y enough for you, fear not! We can add a simple set of wrappers to enable you to write tests in the beloved Given, When, Then style.

Given I whip up a quick class which wraps around Actor...

class GherkinKeyword { let actor: Actor init(_ name: String) { self.actor = Actor(called: name) } }

When I make some GherkinKeyword subclasses...

class Given: GherkinKeyword { func has(_ task: Task) { actor.has(task) } } class When: GherkinKeyword { func attemptsTo(_ task: Task) { actor.attemptsTo(task) } } class Then: GherkinKeyword { func sees(_ question: Question) { actor.sees(question) } }

Then I can write tests using Gherkin-like syntax!

Given("Bob").has(StartedWith.sixBagItems()) When("Bob").attemptsTo(RemoveBagItem.inPosition(1)) Then("Bob").sees(Bag.Items.displayedCount(is: 5))

Notice that Given only allows you to use has(_:) (the setup task method), When only allows you to use attemptsTo(_:) (the method for performing the task under test) and Then only allows you to use sees(_:) (the questioning/assertion method). This allows your tests' structure to be more easily visible.

Unfortunately, since Given, When and Then are all separate objects, we have to create a new Actor for every step. There's more we can do, though.

We can refactor a little so that we reuse the name String:

let bob = "Bob" Given(bob).has(StartedWith.sixBagItems()) When(bob).attemptsTo(RemoveBagItem.inPosition(1)) Then(bob).sees(Bag.Items.displayedCount(is: 5))

Or we could refactor a bit more, and have GherkinKeyword (and its descendants) take an Actor in its initializer, rather than a String for the Actor's name.

class GherkinKeyword { let actor: Actor init(_ actor: Actor) { self.actor = actor } }

Now, if we create the Actor at the beginning of the test, like in the 'vanilla' example above, the Actor can be passed into each of the Given, When and Then initializers, so that each test doesn't require the creation of multiple Actors.

let bob = Actor(called: "Bob") Given(bob).has(StartedWith.sixBagItems()) When(bob).attemptsTo(RemoveBagItem.inPosition(1)) Then(bob).sees(Bag.Items.displayedCount(is: 5))

This is part 2 of 3 in a series about using the Screenplay pattern in Swift.

Part 1: What is the Screenplay Pattern?

Part 3: Writing Screenplay Tests in Swift

Part 1 of this series on the Screenplay pattern explained what the Screenplay pattern is, and where its value lies. In this part, we'll go through each of the entities in the Screenplay pattern in more detail, using a Swift + XCTest implementation of Screenplay, focusing around the 'bag' domain area of an e-commerce application.

Element Location

For each domain area of your app, you will need to locate the elements which are part of that domain area. Element Locators (or 'Elements entities') will encapsulate the knowledge of how to locate the elements in each domain of the application under test.

Since this example is for tests which only ever use a single instance of the application under test, the reference to the application is created (statically) by the Elements entity. When using XCTest, any instance of XCUIApplication will be paired with your application under test by default. XCUIApplication gives you access to the elements of the application under test, which will allow you to expose elements to Actions and Questions without exposing the knowledge of how to find them. The Elements entity does not expose the app driver as part of its public or internal interface to help ensure that only Elements entities have direct access to XCUIApplication, and prevent any other types of objects from taking on the responsibility of locating elements of the application.

import XCTest enum BagElements { private static let app = XCUIApplication() static func cell(at index: Int) -> XCUIElement { return app.cells.element(boundBy: index) } static func removeButton(forCellAt index: Int) -> XCUIElement { return cell(at: index).buttons["delete"] } static var cells: XCUIElementQuery { return app.cells } }

The BagElements enum provides static functions, exposing all of the elements in the 'bag' domain of the app which are needed to execute the functional tests.

Elements entities should return XCUIElement objects whenever possible, however, in some situations, it is not possible to narrow the query down to a single object. This is often the case for groups of similar elements or repeated elements, like the list of item cells in the user's bag. In these cases, you may expose an XCUIElementQuery to allow Questions to query the group of elements as a whole, or to allow Actions to execute the same action on multiple elements at once.

Actions

Actions are static methods which encapsulate the implementation details of how to interact with elements using XCTest (or your test framework of choice) in order to perform certain actions.

Actions are grouped by domain area, so related actions may be grouped together under a single entity.

import XCTest enum BagActions { static func showRemoveItemButton(forItemAt index: Int) { let cell = BagElements.cell(at: index) cell.swipeLeft() } static func confirmRemoveItem(forItemAt index: Int) { let button = BagElements.removeButton(forCellAt: index) button.tap() } }

For each interaction which can be made by the user, there should be an action. In some cases, it may be helpful to have multiple levels of Actions (Actions which encapsulate groups of Actions), to provide a cleaner interface at the Task level.

Actions will be used by Task implementations, and will not be visible at the test level, so it's not necessary for Actions to present behavioural interfaces.

Tasks

Tasks are objects which encapsulate the actions which need to be executed in order to complete a particular task. Some tasks may only need one Action to be completed. Other tasks may need multiple Actions to be undertaken. The job of a Task is to allow the author of a test to achieve some behaviour in a single line of code; without having to explicitly direct the test on what to interact with, and how to interact with it. As such, Tasks should exhibit a behavioural interface.

Task objects must conform to the Task protocol in order to be accepted by an Actor.

public protocol Task { func perform() }

When the Task is given to an Actor, the Actor will perform() the Task. In order to ensure that the task is performed correctly, your implementation of perform() must execute some Actions.

This example implementation of a Task shows how you would construct a Task for removing an item from the user's bag, using the Actions we defined in the Actions section above.

Tasks do not need to import XCTest as all of the work with XCTest entities is done by Actions and Element Locators.

struct RemoveBagItem: Task { let index: Int /// Executes actions to remove an item from the bag. func perform() { BagActions.showRemoveItemButton(forItemAt: index) BagActions.confirmRemoveItem(forItemAt: index) } /// Creates a Task for removing a bag item at the given `index`. /// /// - Parameter index: Index of the bag item to be removed. Bag items are 0-indexed. /// - Returns: RemoveBagItem Task which, when performed, will remove the item in the user's bag at the given `index`. static func inPosition(_ index: Int) -> RemoveBagItem { return RemoveBagItem(index: index) } }

Tasks are small, focused objects. As your test suite grows, it will begin to contain many Tasks for each different domain being tested. Each different Task should have its own object definition with a unique perform() implementation and at least one factory method (like inPosition(_:)). Some tasks may have additional factory methods for convenience. If many tests are removing bag items in position 0, you may want to create a convenience factory method called inPosition0().

Remember when naming your Task and its factory methods that it will be used in the format:

Task.factoryMethodName(with: someValue)

So be sure to name your Tasks and factory methods in a way that makes sense as part of this sentence-like code structure.

RemoveBagItem.inPosition(3)

Prefer method and function names that make use sites form grammatical English phrases. - Swift API Design Guidelines

Questions

Questions must conform to the Question protocol in order to be accepted by an Actor.

public protocol Question { func ask() }

When the Question is given to an Actor, the Actor will ask() the Question. In order to ensure that the question is answered, you must make sure that your implementation of the ask() method makes an assertion, failing the test if the answer is incorrect.

This example implementation of a Question shows how you would construct a Question about the number of items in the user's bag.

import XCTest enum BagItems: Question { case count(actual: Int, expected: Int) /// Ask this question. /// /// If the answer is incorrect, the test will fail. func ask() { switch self { case .count(let actualValue, let expectedValue): XCTAssertEqual(actualValue, expectedValue) } } /// Create a question about the number of bag items being displayed. /// /// - Parameter expectedValue: The number of bag items you expect to be displayed. /// - Returns: A Question about the number of bag items being displayed. When asked, this Question will compare the number of bag items displayed with the given `expectedValue`. If they are not equal, the test will fail. static func displayedCount(is expectedValue: Int) -> BagItems { let actualValue = BagElements.cells.count return count(actual: actualValue, expected: expectedValue) } }

This implementation could be extended to ask more questions about the state of the bag, such as whether a certain item is present in the bag, or what the total price is for all the items in the bag. For each different question you want to ask about this part of the application under test, add another case with the associated values needed to make your assertion (like count(actual:expected:)), and add another static factory method (like displayedCount(is:)) to create questions using that format.

Remember when naming your Question and its factory methods that they will be used in the format:

QuestionDomainArea.factoryMethodName(is: someValue)

So be sure to name your Question entities and factory methods in a way that makes sense as part of this sentence-like code structure.

BagItems.displayedCount(is: 5)

Prefer method and function names that make use sites form grammatical English phrases. - Swift API Design Guidelines

Actors

The Actor is the point of use for Tasks and Questions. It uses the Interface Segregation and Dependency Inversion principles (the I and D in SOLID) to accept any Task or Question.

You can give your Actor a name if you'd like. This isn't strictly necessary, but may help to add context to the test when it is written. In a scenario with multiple Actors, having a name will help you to differenciate between them, which can be particularly helpful when debugging.

Actors do not need to import XCTest. Any interactions with XCTest entities should be handled by other objects.

public class Actor { let name: String public init(called name: String) { self.name = name } // MARK: Public methods /// Make this Actor perform a setup task. /// /// Interacts with the application by performing the given `task`. /// /// - Parameter task: Task to be performed. public func has(_ task: Task) { perform(task) } /// Make this Actor perform a task which should cause your expected outcome. /// /// Interacts with the application by performing the given `task`. /// /// - Parameter task: Task to be performed. public func attemptsTo(_ task: Task) { perform(task) } /// Ask a question about what this Actor sees on the screen to verify that it is what you expect. /// /// Enquires about the state of the application using the given `question`. /// /// - Parameter question: Question to be answered. public func sees(_ question: Question) { ask(question) } // MARK: Private methods /// Asks the given `question`. private func ask(_ question: Question) { question.ask() } /// Performs the given `task`. private func perform(_ task: Task) { task.perform() } }

The has(_:), attemptsTo(_:) and sees(_:) methods are available publicly to allow test writers to use them. The private ask(_:) and perform(_:) methods separate the use of the Task and Question interfaces from the implementation of the public-facing methods. This means that in the event that the Task or Question interfaces change, that change will only need to be made in the relevant private method, rather than all of the public methods which use a Task or Question.

Actors are created and used inside test methods to facilitate the actions and assertions of a test.

This is part 1 of 3 in a series about using the Screenplay pattern in Swift.

Part 2: Screenplay Entities with XCTest and Swift

Part 3: Writing Screenplay Tests in Swift

The Screenplay pattern for UI testing is an 'upgrade' to the Page Object pattern.

The Page Object pattern is a great UI testing pattern which provides a simple, easy-to-understand architecture for your UI testing code. It has a low barrier to entry, and is well-suited to those without much programming experience. Unfortunately, to make the Page Object pattern accessible to new programmers, it does make some sacrifices with regards to scalability.

The Screenplay pattern aims to solve the Page Object pattern's lack of scalability by adhering to SOLID principles.

It should be noted that by improving on the scalability of the Page Object pattern, the barrier to entry does become higher in terms of understanding required. Therefore, when choosing between the Page Object and Screeplay patterns, you should decide whether accessibility or scalability matter more to you.

In the Screenplay pattern, the responsibilities which would have been taken on by a page object in the Page Object pattrn are split up into multiple objects, in order to satisfy the Single Responsibility principle (the S in SOLID). These responsibilities are:

Encapsulating element location details

Encapsulating interaction implementation details

Providing a behavioural interface for user actions

Providing a state inquiry interface for the application under test

Depending on your UI testing requirements, there may be an additional responsibility; holding a reference to the instance of the application under test. This responsibility is only useful if you are testing more than one application instance at once. For now, let's assume you're just testing a single application at a time.

Screenplay Architecture

Element Locators encapsulate element location details.

Actions encapsulate interaction implementation details.

Tasks provide a behavioural interface for user actions.

Questions handle state enquiries.

Actors facilitate the execution of Actions and answering of Questions.

This is part 1 of 3 in a series about using the Screenplay pattern in Swift.

Part 2: Screenplay Entities with XCTest and Swift Part 3: Writing Screenplay Tests in Swift

The Screenplay pattern for UI testing is an 'upgrade' to the Page Object pattern.

The Page Object pattern is a great UI testing pattern which provides a simple, easy-to-understand architecture for your UI testing code. It has a low barrier to entry, and is well-suited to those without much programming experience. Unfortunately, to make the Page Object pattern accessible to new programmers, it does make some sacrifices with regards to scalability.

The Screenplay pattern aims to solve the Page Object pattern's lack of scalability by adhering to SOLID principles.

It should be noted that by improving on the scalability of the Page Object pattern, the barrier to entry does become higher in terms of understanding required. Therefore, when choosing between the Page Object and Screeplay patterns, you should decide whether accessibility or scalability matter more to you.

In the Screenplay pattern, the responsibilities which would have been taken on by a page object in the Page Object pattrn are split up into multiple objects, in order to satisfy the Single Responsibility principle (the S in SOLID). These responsibilities are:

Encapsulating element location details

Encapsulating interaction implementation details

Providing a behavioural interface for user actions

Providing a state inquiry interface for the application under test

Depending on your UI testing requirements, there may be an additional responsibility; holding a reference to the instance of the application under test. This responsibility is only useful if you are testing more than one application instance at once. For now, let's assume you're just testing a single application at a time.

Screenplay Architecture

Element Locators encapsulate element location details.

Actions encapsulate interaction implementation details.

Tasks provide a behavioural interface for user actions.

Questions handle state enquiries.

Actors facilitate the execution of Actions and answering of Questions.