Running locally

To run Playmatic tests locally, use the Playwright runner. All Playmatic SDK capabilities like AI actions and the environment manager are fully Playwright compatible, allowing you to get the benefit of AI reasoning with all the built-in tools of Playwright.

Prerequisites

Before running tests locally, ensure you have:

Node.js 18 or newer: Required for Playwright & Playmatic SDK
Playmatic tests: Tests written in the playmatic/ directory
Configuration files: playmatic.config.ts and playwright.config.ts in your test directory

Step 1: Navigate to your test directory

Navigate to the playmatic/ directory in your project root where your Playmatic tests are located:

cd playmatic

Step 2: Install the dependencies to run tests locally

pnpm install

npx playwright install

Step 3: Add your Playmatic API key

The API key is required for AI actions (like aiClick and aiVerify) to work locally. Go to your Playmatic dashboard → Settings and create an API key. Then, add it to your shell environment:

export PLAYMATIC_API_KEY=YOUR_API_KEY

Tests that only use standard Playwright actions will run without an API key. AI actions require authentication to the Playmatic service.

Step 4: Configure your test environment

Initialize your test environment in the playwright.config.ts file. The environment determines which baseUrl and variables your tests will use.

Learn more about configuring different testing environments in the environment manager

playwright.config.ts

import { setEnvironment } from "@playmatic/sdk";
import { defineConfig, devices } from "@playwright/test";
import playmaticConfig from "./playmatic.config";

// Set environment globally (agent will export PLAYMATIC_TEST_ENV, fallback to default env)
const envName = process.env.PLAYMATIC_TEST_ENV || playmaticConfig.defaultEnv;
setEnvironment(playmaticConfig.env[envName]);

export default defineConfig({
  testDir: "./tests",
  use: {
    baseURL: playmaticConfig.env[envName].baseUrl,
    trace: "on",
    screenshot: "on",
    video: "on",
  },
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },
  ],
});

By default, tests will use the defaultEnv specified in your playmatic.config.ts. To run tests against a different environment, set the PLAYMATIC_TEST_ENV variable:

# Run against staging environment
PLAYMATIC_TEST_ENV=staging npx playwright test

# Run against production environment
PLAYMATIC_TEST_ENV=production npx playwright test

Step 5: Run the tests

# Run all tests
npx playwright test

# View the test report
npx playwright show-report

Common Playwright Commands

Here are useful commands for running and debugging your Playmatic tests:

# Run a specific test file
npx playwright test login.spec.ts

# Run tests in headed mode (see the browser)
npx playwright test --headed

# Run tests with Playwright UI (interactive mode)
npx playwright test --ui

# Run tests in debug mode (step through with debugger)
npx playwright test --debug

# Run tests on a specific browser
npx playwright test --project=chromium

# Run tests with a specific environment
PLAYMATIC_TEST_ENV=staging npx playwright test

# Update snapshots (if using visual regression)
npx playwright test --update-snapshots

Learn more about Playwright test runner options in the Playwright documentation.

GETTING STARTED

TEST DEVELOPMENT

RUNNING TESTS

Prerequisites

Step 1: Navigate to your test directory

Step 2: Install the dependencies to run tests locally

Step 3: Add your Playmatic API key

Step 4: Configure your test environment

Step 5: Run the tests

Common Playwright Commands

​Prerequisites

​Step 1: Navigate to your test directory

​Step 2: Install the dependencies to run tests locally

​Step 3: Add your Playmatic API key

​Step 4: Configure your test environment

​Step 5: Run the tests

​Common Playwright Commands

Prerequisites

Step 1: Navigate to your test directory

Step 2: Install the dependencies to run tests locally

Step 3: Add your Playmatic API key

Step 4: Configure your test environment

Step 5: Run the tests

Common Playwright Commands