Skip to main content
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.