Reference
Playwright

Load testing with Playwright and Artillery

Overview

Built-in since: v2.0.0-33

Playwright (opens in a new tab) is a modern browser automation framework by Microsoft. Artillery supports running Playwright-based scripts as load tests, including running Playwright at scale using AWS Fargate.

Features

→ See Why load test with headless browsers?

Current limitations

  • Test functions have to be written in Javascript (if you have existing Playwright code in TypeScript, it will need to be transpiled to JS first)
  • Only Chrome is available. Restricting the integration to just one browser improves startup time performance for large load tests and does not have any consequential effects on the results of load tests themselves.

Usage

The Playwright engine is built into Artillery.

Create a new Artillery script in hello-world.yml:

config:
  target: https://www.artillery.io
  # Load the Playwright engine:
  engines:
    playwright: {}
  # Path to JavaScript file that defines Playwright test functions
  processor: "./flows.js"
scenarios:
  - engine: playwright
    testFunction: "helloFlow"

Create a test function in flows.js:

(Note: this script was generated with playwright codegen (opens in a new tab). page is an instance of Playwright page (opens in a new tab).)

module.exports = { helloFlow };
 
async function helloFlow(page) {
  //
  // The code below is just a standard Playwright script:
  //
  // Go to https://artillery.io/
  await page.goto("https://www.artillery.io/");
  // Click text=Pricing
  await page.click("text=Cloud");
}

Run it:

artillery run hello-world.yml

Artillery will run the test and automatically record front-end performance metrics that measure perceived load speed (opens in a new tab) such as LCP and FCP:

--------------------------------
Summary report @ 11:24:53(+0100)
--------------------------------

vusers.created.total: ....................................... 1
vusers.completed: ........................................... 1
vusers.session_length:
  min: ...................................................... 5911.7
  max: ...................................................... 5911.7
  mean: ..................................................... 5911.7
  median: ................................................... 5944.6
  p95: ...................................................... 5944.6
  p99: ...................................................... 5944.6
browser.page.FCP.https://artillery.io/:
  min: ...................................................... 1521.1
  max: ...................................................... 1521.1
  mean: ..................................................... 1521.1
  median: ................................................... 1525.7
  p95: ...................................................... 1525.7
  p99: ...................................................... 1525.7
browser.page.LCP.https://artillery.io/:
  min: ...................................................... 1521.1
  max: ...................................................... 1521.1
  mean: ..................................................... 1521.1
  median: ................................................... 1525.7
  p95: ...................................................... 1525.7
  p99: ...................................................... 1525.7
browser.page.FCP.https://artillery.io/cloud/:
  min: ...................................................... 205.3
  max: ...................................................... 205.3
  mean: ..................................................... 205.3
  median: ................................................... 206.5
  p95: ...................................................... 206.5
  p99: ...................................................... 206.5
browser.page.LCP.https://artillery.io/cloud/:
  min: ...................................................... 205.3
  max: ...................................................... 205.3
  median: ................................................... 206.5
  p95: ...................................................... 206.5
  p99: ...................................................... 206.5

Configuration

The underlying Playwright instance may be configured through config.engines.playwright.

You can pass the following options in:

Example 1: turn off headless mode

You can turn off the default headless mode to see the browser window for local debugging by setting the headless (opens in a new tab) option.

config:
  engines:
    playwright:
      launchOptions:
        headless: false

Example 2: set extra HTTP headers

This example sets the extraHTTPHeaders (opens in a new tab) option for the browser context that is created by the engine.

config:
  engines:
    playwright:
      contextOptions:
        extraHTTPHeaders:
          x-my-header: my-value

Aggregate metrics by scenario name

By default metrics are aggregated separately for each unique URL. When load testing the same endpoint with different/randomized query params, it can be hepful to group metrics by a common name.

To enable the option pass aggregateByName: true to the playwright engine and give a name to your scenarios:

config:
  target: https://artillery.io
  engines:
    playwright: { aggregateByName: true }
  processor: "./flows.js"
scenarios:
  - name: blog
    engine: playwright
    testFunction: "helloFlow"

flows.js:

module.exports = { helloFlow };
 
function helloFlow(page) {
  await page.goto(`https://artillery.io/blog/${getRandomSlug()}`);
}

This serves a similar purpose to the useOnlyRequestNames option from the metrics-by-endpoint plugin.

Show Web Vital metrics for all pages

Artillery only displays Web Vital metrics for a URL that starts with the target URL. This avoids it showing for pages that don't belong to your website, like iframes. If you want to see Web Vital metrics for all pages, you can set showAllPageMetrics to true in your config:

config:
  engines:
    playwright: { showAllPageMetrics: true }

Extended Metrics

If enabled, Artillery will collect additional metrics.

You can enable it by setting extendedMetrics to true in your config:

config:
  engines:
    playwright: { extendedMetrics: true }

Test function API

Page argument

By default, only the page argument (see Playwright's page API (opens in a new tab)) is required for functions that implement Playwright scenarios, e.g.:

module.exports = { helloFlow };
 
async function helloFlow(page) {
  // Go to https://artillery.io/
  await page.goto("https://artillery.io/");
}

Virtual user context and events arguments

The functions also have access to the virtual user context, which can be used for several purposes:

  • Accessing scenario (and environment) variables for different virtual users (vuContext.vars);
  • Getting the current virtual user ID (vuContext.vars.$uuid);
  • Getting the scenario definition for the scenario currently being run by the virtual user (vuContext.scenario), including its name.

Additionally, the events argument can be used to track custom metrics.

module.exports = { helloFlow };
 
async function helloFlow(page, vuContext, events) {
  // Increment custom counter:
  events.emit("counter", `user.${vuContext.scenario.name}.page_loads`, 1);
  // Go to https://artillery.io/
  await page.goto("https://artillery.io/");
}

test.step argument

Added in: v2.0.0-38

The final argument of the function is test, which contains the step property. The API for test.step is similar to Playwright's own test.step, which allows you to re-use similar code. The purpose in Artillery is slightly different: to emit custom metrics that represent how long each step takes.

async function loginSearchAndLogout(page, vuContext, events, test) {
   //1. simply add this line to your scenario function, or use test.step below instead
  const { step } = test;
  const userid = vuContext.vars.userid;
  const recordid = vuContext.vars.recordid;
 
  //2. wrap any logic you have in steps (sometimes you might already have something like this done from existing playwright tests)
  await step("landing_page", async () => {
    await page.goto('https://internaltesturl.com/landing');
    await page.getByLabel('id-label').fill( `${userid}` );
    await page.getByLabel('Password').fill(`${password}`);
  })
 
  await step("submit_login", async () => {
    await page.getByRole('button', { name: 'Submit' }).click();
    await page.getByPlaceholder('enter request id').fill(`${recordid}`);
  })
 
  await step("search_record", async () => {
    await page.getByRole('button', { name: 'Go' }).click();
    await page.locator('css=button.avatar-button').click();
  })
 
  await step("logout", async () => {
    await page.getByText('Logout').click();
  })
}

The above code will now emit custom metrics for each step in addition to the default metrics:

browser.step.landing_page:
  min: ......................................................................... 87
  max: ......................................................................... 150
  mean: ........................................................................ 118.5
  median: ...................................................................... 89.1
  p95: ......................................................................... 89.1
  p99: ......................................................................... 89.1
browser.step.submit_login:
  min: ......................................................................... 300
  max: ......................................................................... 716
  mean: ........................................................................ 571.6
  median: ...................................................................... 561.2
  p95: ......................................................................... 561.2
  p99: ......................................................................... 561.2
browser.step.search_record:
  min: ......................................................................... 287
  max: ......................................................................... 801
  mean: ........................................................................ 544.6
  median: ...................................................................... 290.1
  p95: ......................................................................... 290.1
  p99: ......................................................................... 290.1
browser.step.logout:
  min: ......................................................................... 52
  max: ......................................................................... 334
  mean: ........................................................................ 193.1
  median: ...................................................................... 140.2
  p95: ......................................................................... 200.4
  p99: ......................................................................... 200.4

Metrics reported by the engine

In addition to the default metrics reported by Artillery, the Playwright engine reports the following metrics:

MetricTypeDescription
browser.http_requestsCounter

(count)

Number of HTTP requests made by all browsers during this time period.
browser.page.TTFB.<page_url>.<aggregation>Histogram

(milliseconds)

Time To First Byte (opens in a new tab) (Web Vital metric) measurement for a specific page_url.
browser.page.FCP.<page_url>.<aggregation>Histogram

(milliseconds)

First Contentful Paint (opens in a new tab) (Web Vital metric) measurement for a specific page_url.
browser.page.LCP.<page_url>.<aggregation>Histogram

(milliseconds)

Largest Contentful Paint (opens in a new tab) (Core Web Vital metric) measurement for a specific page_url.
browser.page.FID.<page_url>.<aggregation>Histogram

(milliseconds)

First Input Delay (opens in a new tab) (Core Web Vital metric) measurement for a specific page_url (if available).
browser.page.CLS.<page_url>.<aggregation>Histogram

(shift score)

Cumulative Layout Shift (opens in a new tab) (Core Web Vital metric) measurement for a specific page_url (if available).

Extended metrics

If extendedMetrics is enabled, the following metrics are also reported:

MetricTypeDescription
browser.page.domcontentloadedCounter

(count)

Number of DOM Content Loaded (opens in a new tab) events across all pages.
browser.page.domcontentloaded.<page_url>Counter

(count)

Number of DOM Content Loaded (opens in a new tab) events for a specific page_url.
browser.page.dominteractive.<aggregation>Histogram

(milliseconds)

Measurement of time taken for DOM to become interactive (opens in a new tab), across all pages.
browser.page.dominteractive.<page_url>.<aggregation>Histogram

(milliseconds)

Measurement of time taken for DOM to become interactive (opens in a new tab), for a specific page_url.
browser.memory_used_mb.<aggregation>Histogram

(megabytes)

Measurement of usedJSHeapSize.

If test.step() API is used, the following additional histogram is reported:

  • browser.step.<step_name>.<aggregation> (milliseconds) - measurement of time taken for each step in the scenario.

Why load test with headless browsers?

Load testing complex dynamic web apps can be time consuming, cumbersome, and brittle compared to load testing pure APIs and backend services. The main reason is that testing web apps requires a different level of abstraction: whereas APIs work at API endpoint level, when testing web apps pages and user flows is a much more useful abstraction that maps onto how the web app is actually used.

Without Playwright

  • Figure out which HTTP APIs are used by the web page
  • Figure out what actions in the UI trigger calls to which APIs
  • Figure out what in-page JavaScript code does and how it interacts with the backend
  • Try to mimic realistic load on the backend at protocol level or by using HAR files
  • Ignore limitations with how dynamic such tests can be, and accept how brittle and time consuming maintetance is going to be

With Playwright

  • Just write UI-centric code and let the web app itself call the backend
  • Run lots of Playwrigth scripts to generate load on the backend

Testing HTTP APIs vs dynamic web apps

Ultimately, testing a backend HTTP API is very different from testing a web application that may use many such APIs and use client-side JavaScript to communicate with those APIs.

HTTP APIs & microservicesWeb apps
Abstraction levelHTTP endpointWhole page
Surface areaSmall, a handful of endpointsLarge, calls many APIs. Different APIs may be called depending on in-page actions by the user
Formal specUsually available (e.g. as an OpenAPI spec)No formal specs for APIs used and their dependencies. You have to spend time in Dev Tools to track down all API calls
In-page JSIgnored. Calls made by in-page JS have to be accounted for manually and emulatedRuns as expected, e.g. making calls to more HTTP endpoints