> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playmatic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Running locally

> Set up and run Playmatic tests on your local development machine

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](https://nodejs.org/en/download/)**: 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:

```bash theme={null}
cd playmatic
```

## Step 2: Install the dependencies to run tests locally

```bash theme={null}
pnpm install
```

```bash theme={null}
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:

```bash theme={null}
export PLAYMATIC_API_KEY=YOUR_API_KEY
```

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

## 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.

<Tip>Learn more about configuring different testing environments in the [environment manager](/test-development/environment-management)</Tip>

```typescript playwright.config.ts theme={null}
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:

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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](https://playwright.dev/docs/running-tests).