Why are page elements questions?

[driuzzo]

Hello! I have downloaded serenity-playwright-template and I want to understand why do we consider page elements as questions?

[jan-molak]

I love your question, so I'd like to offer you not just an answer, but also my thinking behind it.

TL;DR - What are page elements?

Page elements are standardised abstractions around web integration tool-specific representations of web elements, such as Element in Selenium-based tools or Locator in Playwright.

A construct like PageElement.located(By.css('...')) returns a composable Question implementation (a MetaQuestionAdapter to be precise) that allows for composing page elements together, or mapping them to transform their value.

import { By, PageElement, Text } from '@serenity-js/web'

export const basketTotal = () =>
  PageElement.located(By.css('#basket .total'))
    .describedAs('basket total')

export const basketTotalAmount = () =>
  Text.of(basketTotal())                // <- Compose PageElement with question about Text
    .trim()                             // <-   Compose with a question that trims the result
    .replace('£', '')                   // <-   Compose with a question that removes the currency symbol
    .as(Number)                         // <-   Compose with a question that converts the result to Number
    .describedAs('basket total price')  // <- Custom description (optional)

The benefit of using Serenity/JS page element abstractions is that you can make your test code agnostic of the underlying web integration code and reuse the same code across projects and teams.

But why?

To answer why page elements are modelled the way they are, I'd like to share with you my design journey over the past years.

The beginnings

In our initial work on the Screenplay Pattern, there were no "page elements"; those came much later. Initially, we had a concept of a "target". We'd use the "target" to encapsulate the description of a web element and its CSS locator. You'll see our early articles from 2016 use "targets" in the code examples like so:

// Java
public class ToDoList {
  public static Target WHAT_NEEDS_TO_BE_DONE = 
    Target.the("'What needs to be done?' field")
      .locatedBy("#new-todo");
        
  // ...

Targets were not part of the Screenplay Pattern and were more of an add-on, sitting somewhere on the sidelines.

Serenity/JS v1, released around that time, followed a similar model. The main difference between the first Java and JS implementation was that Serenity/JS supported pluggable Selenium / Protractor selectors rather than being tied to CSS only:

// JS
Target.the("'What needs to be done?' field")
      .located(by.css("#new-todo"));  // or by.xpath, by.id, etc.

Even though "targets" served their initial purpose, as teams using both Serenity BDD and Serenity/JS began automating more and more sophisticated websites and web apps, the design limitations began to show. For example, reusing partial selectors relied on string concatenation and token replacement, which felt awkward. Working with lists of elements and picking them based on some criteria was hard. Not to mention that new web integration tools, such as WebdriverIO, have entered the stage, so relying on Selenium-based by.* selectors was no longer sufficient as I had to support other tools, too.

At that time, I realised that Serenity/JS:

• needs to support other web integration tools without affecting the implementation, so that developers could switch from Protractor to WebdriverIO without changing their code too much
• needs to simplify working with collections of elements.

The second attempt

In Serenity/JS v2, I created two web integration packages - @serenity-js/protractor and @serenity-js/webdriverio. They still used the idea of "targets", but worked with by.* selectors from their respective web integration tools.

In a Protractor test, we'd have:

import { Target } from '@serenity-js/protractor';
import { by } from 'protractor';

const basketItems = Target.all('items in the basket').located(by.css('ul#basket li'))

In a WebdriverIO test, we'd see:

import { by, Target } from '@serenity-js/webdriverio';

const basketItems = Target.all('items in the basket').located(by.css('ul#basket li'))

The code for each web integration tool would be nearly identical, save for the imports. What it meant is that migrating from Protractor to WebdriverIO would require you to simply find & replace your import statements rather than rewrite your entire test suite. That helped a lot of teams.

The other notable addition was that the Serenity/JS v2 target model allowed for easier filtering based on pluggable criteria. For example:

const basketItems = Target.all('items in the basket')
  .located(by.css('ul#basket li'))
  .where(Text, endsWith('e'))
  .first() 

While much more useful than my first implementation, "targets" were still missing something to become truly portable: Serenity/JS v2 did not implement targets as "questions". They were elegant builders that under the hood resolved to Question<Promise<Element>>, where Element was a Protractor or WebdriverIO representation. That was sufficient for some time as the way Protractor, WebdriverIO and Selenium model an "element" is similar.

But then Playwright came about...

At that time, I came to the following realisation:

• Serenity/JS needed to have its own abstraction over Selenium/WebdriverIO/Playwright/Whatever-comes-next
• The original design of "targets" was no longer sufficient and had to be rethought. I also wanted the representation of interactive elements to become a first-class citizen.

Abandoning the targets

With Serenity/JS v3, I decided to depart from the original "target" model altogether.

To address the first challenge, I created Serenity/JS By. When you use By.css, By.id, By.role, and so on, you always use the same consistent API imported from @serenity-js/web. You no longer need to mix Serenity/JS code with lower-level abstractions provided by the web integration tool.

However, abstracting the selectors required me to abstract the representation of web elements as well.
That's how I arrived at the PageElement and PageElements classes.

I also realised that a "page element" is closely related to a "question", but is not a question itself. If it was a question, what would that question resolve to? Probably an Element or a Locator, but then we're back to square one... Page element is a wrapper around the native "element", that offers standardised methods like click() or enterValue() and guarantees consistent behaviour across all the supported web integration tools like Protractor, Playwright, WebdriverIO + Selenium, WebdriverIO + Puppeteer (as proven by hundreds of integration tests)

PageElements are then an implementation of a Serenity/JS List and allow for filtering, mapping, and looping over collections of elements.

The introduction of standardised By, PageElement and PageElements classes then opened the doors to Serenity/JS Page Element Query Language, which I'm hoping to evolve further in future releases.

It also enabled test code reuse across web integration tools. For example, you can write a web component test using Serenity/JS + Playwright Component Test Runner, and then plug your test code into an end-to-end test suite using Serenity/JS + WebdriverIO and running against a remote Selenium grid.

---

I hope this story has helped you to understand how and why I arrived at the current design. It might have also gave you hints of where I might take it next ;)