Create a new synthetic test

[beta] This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. To write synthetic tests for your application, you’ll need to know basic JavaScript and Playwright syntax. Synthetics agent exposes a an API for creating and running tests:

The journey function takes a single parameter, name, and provides access to page, params, browser, and context:

Putting it all together, a basic, two step journey might look something like this:

journey("Journey name", ({ page }) => {
    step("Step 1 name", () => {
      // Do something here
    })
    step("Step 2 name", () => {
      // Do something else here
    })
});

Steps can be as simple or complex as you need them to be. The Playwright page API reference will be your friend while writing tests.

A basic first step might simply load a page:

await page.goto('https://elastic.github.io/synthetics-demo/'); 

A more complex second step might wait for a page element to be selected, and then ensure that it matches an expected value. Consider the following HTML snippet:

<header class="header">
  <h1>todos</h1>
  <input class="new-todo"
    autofocus autocomplete="off"
    placeholder="What needs to be done?">
</header>

You can verify that new-todo class element contains the expected placeholder (input hint) with the following test:

step("Check placeholder text", async () => {
  const placeholderValue = await page.getAttribute(
      'input.new-todo',
      'placeholder'
  ); 
  expect(placeholderValue).toBe('What needs to be done?'); 
})

A complete example of a basic synthetic test looks like this:

import { journey, step, expect } from '@elastic/synthetics';

journey("Ensure placeholder is correct", ({page}) => {
    step("go to todos demo page", async () => {
      await page.goto('https://elastic.github.io/synthetics-demo/');
    })
    step("assert placeholder text", async () => {
      const placeholderValue = await page.getAttribute(
        'input.new-todo',
        'placeholder'
      );
      expect(placeholderValue).toBe('What needs to be done?');
    })
});

As explained in the quickstart, there are two ways to run synthetic tests:

Which option is right for you? That depends. If you want to invoke a single journey with few steps, an inline journey might be the easiest workflow — you only need to write your tests into your heartbeat.yml file.

Note that you can only paste the steps into an inline script, so these cannot be dependent on any packages that you may want to import. If you do have any dependencies, these would need to be defined with an import outside of the journey object and run via a test suite. If you have a complex test suite, or your tests need to live with your application code, you’re likely better off setting up a synthetic test suite.

The easiest way to run a synthetic test is by creating an inline journey. The journey keyword isn’t required, and access to variables like page and params is automatic. Remember you cannot import any dependencies using inline scripts.

Copy and paste your test steps into heartbeat.yml. Heartbeat spawns a separate Node.js process, schedules your tests, and runs them on a chromium browser. You don’t need to worry about anything else.

An example, short.js, is provided in the elastic/synthetics GitHub repository:

// test-homepage-hover.js
step("load homepage", async () => {
    await page.goto('https://www.elastic.co');
});
step("hover over products menu", async () => {
    await page.hover('css=[data-nav-item=products]');
});

To run this, or any other inline example locally, change into the directory of your test, and pipe the file contents to the npx @elastic/synthetics command.

For example:

cat examples/inline/short.js | npx @elastic/synthetics --inline

If everything works as expected, you’ll get the similar response:

Journey: inline
   ✓  Step: 'load homepage' succeeded (1831 ms)
   ✓  Step: 'hover over products menu' succeeded (97 ms)

 2 passed (2511 ms)

The script can then be copied into your in your heartbeat.yml:

heartbeat.monitors:
- type: browser
  id: elastic-website
  name: Elastic website
  schedule: "@every 1m"
  source:
    inline:
      script: |-
        step("load homepage", async () => {
            await page.goto('https://www.elastic.co');
        });
        step("hover over products menu", async () => {
            await page.hover('css=[data-nav-item=products]');
        });

That’s it! You can either spin up Heartbeat yourself, or jump to Step 3: Run the container, connecting it to Elasticsearch of the Quickstart to use the provided Docker project template.

If you have a suite of tests you’d like to implement, you can use Elastic synthetics as a library. In this method, you use Docker to run both Heartbeat and elastic-synthetics.

Install the @elastic/synthetics package globally to get started:

npm install -g @elastic/synthetics

Now it’s time to write your tests:

At Elastic, we’re fans of examples, so one is provided in the elastic/synthetics repository. If you’d like to test it locally, clone the repo, and install the example:

# Check out the synthetics repo and included examples
git clone git@github.com:elastic/synthetics.git &&\
cd synthetics/examples/todos/ &&\
# Install all required dependencies for the todos example
npm install

You are now inside the a synthetics test-suite, which is also an NPM project. You can now run the provided tests; Note that, by default, only files matching the filename *.journey.(ts|js)* will be run.

# Run tests on the current directory. Please note the dot `.` which indicates
# that we want to run tests on the current directory
npx @elastic/synthetics .

Once you have your tests up and running, follow the steps in the quickstart guide to integrate with the provided Docker project template.