Configuration

The exporter uses a YAML configuration file (usually config.yaml). This file tells the exporter which APIs to check and which UI scenarios to run.

Structure Overview

A basic config.yaml looks like this:

service: "my-e-commerce-app"

api_endpoints:
  - "https://my-e-commerce-app.example.com/api/health"
  - "https://my-e-commerce-app.example.com/api/v1/products"

scenarios:
  - name: "Login Flow"
    steps:
      - name: "navigate_to_login"
        action: "goto"
        target: "https://my-e-commerce-app.example.com/login"
        error_type_name: "navigation_failed"

Global Settings

Field	Description
service	The name of your application. This is used as the service label on all Prometheus metrics.
api_endpoints	A list of URLs. The exporter sends an HTTP GET request to each URL. It records the status code and TLS certificate expiration date.
scenarios	A list of scenarios. Each scenario is a separate UI test.

UI Scenarios and Steps

The scenarios list defines independent UI flows. Inside each scenario, the steps list defines the actions Playwright takes in the browser. If a step fails, the scenario stops. A failure metric is then recorded for that scenario and step.

Each step accepts the following fields:

• name: A name for the step (e.g., fill_password).
• action: The action to run. See Supported Actions.
• target: The URL (for goto), CSS/XPath selector (for interactions), or file path (for screenshot).
• value: (Optional) The text to input. Often used with fill.
• error_type_name: A custom error label sent to Prometheus if this step fails. This helps group alerts (e.g., dashboard_timeout or login_failed).

Supported Actions

Action	Target	Value	Description
goto	URL	-	Navigates the browser to the specified URL and waits for network idle.
fill	Selector	Text	Types the value into the element matching the target selector.
click	Selector	-	Clicks the element matching the target selector.
wait_for_selector	Selector	-	Pauses execution until the element matching the target selector is visible on screen.
screenshot	File path	-	Takes a screenshot of the current page and saves it to the target path.

Secret Management

To keep secrets safe, the exporter can read environment variables at runtime.

If a value string matches ${VARIABLE_NAME}, it is replaced by the value of that environment variable.

  - name: "fill_password"
    action: "fill"
    target: "xpath=//input[@id='password']"
    # The actual password is injected from the host OS environment
    value: "${APP_PASSWORD}" 
    error_type_name: "password_field_missing"

WARNING

Make sure environment variables are passed to the exporter (for example, using Docker -e flags). If they are missing, the value will be empty and the scenario will fail.

Best Practices for Scenarios

When writing scenarios, use these practices to get better alerts.

1. Which Scenarios to Write?

Write scenarios for the critical path of your app. This shows the real health of your product.

• E-Commerce: Write a scenario that logs in, searches for a product, adds it to the cart, and verifies the cart badge updates.
• SaaS Platform: Write a scenario that logs in, navigates to the main dashboard, and creates a new test resource.
• Content Site: Write a scenario that navigates to an article and verifies that the main content and comment section load.

Do not write tests for every small feature. Focus on flows that block users if they break.

2. How to Find XPaths

The easiest way to find XPaths for your target fields is using your browser:

1. Open your target website in Chrome or Edge.
2. Right-click the element you want to interact with and select Inspect.
3. In the Elements panel, right-click the highlighted HTML node.
4. Select Copy -> Copy XPath (or Copy full XPath).
5. Prepend xpath= to the copied string in your config.yaml (e.g., xpath=//*[@id="login-btn"]).

TIP

To make tests less likely to break when the UI changes, use data-testid attributes (like xpath=//button[@data-testid='submit']) instead of long XPaths.

3. Choosing an error_type_name

The error_type_name label is added to the Prometheus metric when a step fails. Choose names that are specific.

• Good: login_button_missing, checkout_timeout, invalid_credentials_error_shown
• Bad: step_failed, error_1, ui_broken

Using specific names helps the on-call engineer know what broke without opening the Grafana dashboard.