# Common Workflows
Source: https://docs.playmatic.ai/getting-started/common-workflows

Learn more about common test creation & maintenance workflows with Playmatic.

Use the `@playmatic` command in Slack to interact with the Playmatic agent. Simply describe what you need in natural language, and the agent will create or update tests in your `playmatic/` folder.

Each workflow below includes example instructions and best practices to help you get reliable and fast coverage.

## Add regression tests

If you need to add coverage for your app, we recommend adding tests incrementally by pages or by feature. Breaking down the task lets the agent create more comprehensive tests.

```markdown wrap theme={null}
@playmatic, add some regression tests for the purchasing flow
```

## Test new features

When testing new features, give the agent clear direction on what "good" looks like. The more specific your description, the better the agent can test the intended behavior. You can provide context in several ways:

**Using a spec or user stories:**

```markdown wrap theme={null}
@playmatic, we're developing a new feature on this branch. Here are the user stories from the spec:
[paste your user stories here]
Can you help me write some tests for this?
```

**Using a test plan:**

```markdown wrap theme={null}
@playmatic, we're developing a new feature. Here's our test plan:
[paste your test plan here]
Can you help me write tests based on this?
```

**Using natural language description:**

```markdown wrap theme={null}
@playmatic, we're developing a new feature on the pr-14124 branch. The user should be able to create, delete, and copy todos in the dashboard. Can you write some tests for this?
```

<Tip>
  The more specific you are about expected behavior, the better the agent will test the intended paths. Vague instructions will only catch obvious functional bugs.
</Tip>

## Maintain existing tests

Update your tests to match changes in your application, ranging from simple selector updates to complete UI redesigns. Just tell the Playmatic agent which tests need updating and point it to the new source of truth (like a specific branch or environment).

**Updating tests after selector changes:**

```markdown wrap theme={null}
@playmatic, the signup test is failing because we updated the form selectors. Can you update it to match what's currently on production?
```

**Updating tests for a UX/UI revamp:**

```markdown wrap theme={null}
@playmatic, we updated the UX of the inventory management feature. Can you update the related tests to match the staging branch?
```

**Rewriting tests after major changes:**

```markdown wrap theme={null}
@playmatic, we fully rebuilt the dashboard. Can you delete the existing dashboard tests and rewrite them based on the new interface?
```

<Tip>
  Update tests after the new working implementation is committed to a branch. This gives the agent a clear source of truth to test against.
</Tip>

## Next steps

<Columns>
  <Card title="Test Development" icon="pencil" href="/test-development/overview">
    Learn more about the test creation & maintenance workflow.
  </Card>

  <Card title="Running Locally" icon="play" href="/running-tests/running-locally">
    Learn about setting up and running Playmatic tests locally.
  </Card>
</Columns>


# Overview
Source: https://docs.playmatic.ai/getting-started/overview

Learn more about Playmatic - your autonomous AI QA team

## What is Playmatic?

Playmatic is an AI QA agent that lives inside your Slack and Github. Talk to it in English, and it will plan, code and validate tests on the cloud.

The tests are written in Playwright, and can be augmented with AI actions for more accurate and reliable test creation & maintenance.

You can run these tests locally and in the CI. Playmatic comes with infrastructure for running tests in the cloud, so you can simply add it to your Github action to get coverage on every PR.

## Why use Playmatic?

* **Faster Coverage**: Describe what you want to test in natural language, and Playmatic will plan, build, validate and create new tests in the background.
* **Powerful AI Augmentations**: Augment Playwright tests with aiClick() and aiVerify() that enable more powerful and less flaky tests.
* **Familiar**: Every test is entirely Playwright compatible, so you can use Playmatic with your existing test infrastructure and system.

```typescript  theme={null}
import { test, expect } from '@playwright/test';
import { env, aiClick, aiVerify } from '@playmatic/sdk';

// Fully Playwright compatible test
test('Playmatic Meeting Calendar Loads', {
  annotation: [
    {
      // Goal is used by the agent for test maintenance
      type: 'playmatic-goal',
      description: 'User navigates to Playmatic.ai, goes to Pricing page, clicks Book Demo, and interacts with calendar'
    }
  ]
}, async ({ page }) => {

  // Test steps are used by the agent for maintenance 
  await test.step('Navigate to Playmatic.ai and go to Pricing page', async () => {
    await page.goto('https://playmatic.ai');
    await page.getByRole('link', { name: /Pricing/i }).click();
    await expect(page).toHaveURL(/pricing/i);
  });

  await test.step('Click Book Demo and interact with calendar in popup', async () => {
    // Use AI actions to click Book Demo button where the copy changes frequently
    const [popup] = await Promise.all([
      page.context().waitForEvent('page'),
      aiClick('Book Demo button', page)
    ]);

    await popup.waitForLoadState('domcontentloaded');
    await expect(popup).toHaveURL(/calendly/);

    // Use AI to interact with 3rd party UI
    await aiVerify('calendar or scheduling interface is visible', popup);
    await aiClick('an available date slot in the calendar', popup);
    await aiVerify('a date is selected or highlighted', popup);
  });
});
```

## Next steps

<Columns>
  <Card title="Quickstart" icon="rocket" href="/getting-started/quick-start">
    Create your first tests using the Playmatic agent in a few minutes.
  </Card>
</Columns>


# Quickstart
Source: https://docs.playmatic.ai/getting-started/quick-start

Welcome to Playmatic!

Get started with Playmatic in just a few minutes. This guide will walk you through creating your first working tests and running them locally.

## Before you begin

Prerequisites:

* A web application to test
* GitHub repository of the web application
* Slack

## Step 1: Create an account on the Playmatic dashboard

Navigate to [https://www.playmatic.ai/login](https://www.playmatic.ai/login) and create an account.

## Step 2: Connect GitHub

Use the link on the dashboard to connect your GitHub and choose a working directory for the Playmatic agent.

<Tip>If you have a monorepo, choose the parent directory so Playmatic has the context of the full codebase when working.</Tip>

## Step 3: Connect Slack

Use the link on the dashboard to connect Playmatic to your workspace.

Now, invite Playmatic into a channel so you can start interacting with it. You can type `/invite @playmatic` in the desired channel.

## Step 4: Create your first tests

Let's start with a simple ask to get coverage on your core flows.

```
> @playmatic write some tests for my core flows
```

You can also ask more specific questions:

```
> @playmatic write a test for my login flow
```

```
> @playmatic write some tests for the API key creation flows
```

Playmatic will now:

1. Read the existing files in your repo
2. Create a test plan with test scenarios covering happy and unhappy paths
3. Ask for approval
4. Ask for help on any prerequisites required to run the test
5. Write and validate tests using its own machine

## Step 5: Review the tests

After a few loops, Playmatic will push a PR for all the working tests, and a draft PR for the tests that need help fixing.

If the Playmatic agent discovers any bugs while building the tests, it will report them in the same Slack thread.

## Step 6: Run the tests

To verify that the test works, we'll run the test locally.

Pull down the branch that Playmatic created for the working tests.

```bash  theme={null}
git checkout <branch_name>
```

Navigate to the Playmatic directory inside your app

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

Install the dependencies

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

Install Playwright and the required dependencies:

```bash  theme={null}
npx playwright install --with-deps chromium
```

Go to your Playmatic dashboard → Settings and create an API key. Then, add the Playmatic key to your runtime environment:

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

Run the tests using Playwright:

```bash  theme={null}
# Run the tests
npx playwright test

# See the report
npx playwright show-report
```

Voila! You have your first working tests, automatically built and validated by AI!

## Pro Tips for beginners

<AccordionGroup>
  <Accordion title="Be specific with your requests">
    If you have a clear idea of the flows that you want the agent to write tests for, be specific.

    Instead of: `@playmatic test the app`.

    Try: `@playmatic test the API key flows in the settings`.
  </Accordion>

  <Accordion title="Provide context to help testing">
    If you believe that the agent might need specific setup or credentials/variables to be able to write and run tests, provide this to the agent.

    `@playmatic, use the API endpoints from the services folder to mock responses.`
  </Accordion>

  <Accordion title="Use step-by-step instructions">
    For complex flows, break down the test into steps.

    ```
    @playmatic, test the DM flow between two users:
    1. Login with James_send account
    2. Send a message to James_receive
    3. Login to James_receive account 
    4. Verify that you see a new message from james_test_send (indicated by the red dot)
    5. Open the message 
    6. Verify that the red dot disappears on that same message in the side pane
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you've learned the basics, explore how Playmatic manages environments and uses AI actions to create reliable tests.

<Columns>
  <Card title="Environment Management" icon="play" href="/test-development/environment-management">
    Learn how to manage test data and variables across different environments.
  </Card>

  <Card title="AI Actions" icon="sparkles" href="/test-development/ai-actions">
    Learn how to augment Playwright tests with AI actions.
  </Card>
</Columns>


# All releases
Source: https://docs.playmatic.ai/release-notes/index

Stay updated with the latest Playmatic releases, features, and improvements

<Update label="September 22, 2025" description="CLI v0.1.15 - Automatic Localhost Tunneling">
  **🔄 Smart Tunneling Enhancement**

  **CLI v0.1.15:**

  * **Automatic localhost detection**: CLI now automatically detects localhost URLs in your configuration and creates tunnels without requiring the `--local` flag
  * **Simplified workflow**: No manual flag needed - just run `playmatic run` and localhost URLs are tunneled automatically
  * **Seamless local development**: Zero-configuration tunneling for any localhost-based environment setup

  **What's New:**
  When your environment configuration contains localhost URLs (like `http://localhost:3000`), Playmatic automatically creates secure HTTPS tunnels without needing the `--local` flag. This streamlines local development testing by removing an extra step from your workflow.
</Update>

<Update label="September 22, 2025" description="CLI v0.1.14 - Enhanced Execution Speed & Reasoning">
  **🚀 Performance & UX Improvements**

  **CLI v0.1.14:**

  * **Optimized execution speed**: Refined computer action delays for faster, more reliable test execution
  * **Enhanced reasoning visibility**: Improved logging and output to better understand agent decision-making

  **What's New:**
  Agent execution is now faster and more transparent, with optimized delays between actions and better visibility into the reasoning process. These improvements result in more efficient test runs while maintaining reliability.
</Update>

<Update label="September 16, 2025" description="CLI v0.1.9 - CI Notifications & Team Collaboration">
  **🔔 Major Feature: Automated CI Notifications**

  **CLI v0.1.9:**

  * **Smart CI notifications**: Automatic Slack notifications for GitHub Actions test runs
  * **Rich context**: Includes repository, branch, commit, and workflow information in notifications
  * **Team-aware**: Respects existing team notification preferences (all results vs issues only)
  * **Multi-channel delivery**: Sends notifications to all Slack channels where your bot is invited
  * **GitHub integration**: Full GitHub metadata captured in CI environments

  **What's New:**
  When your tests run in GitHub Actions, team members now receive rich Slack notifications with test results, GitHub context, and direct links to view detailed results. Configure once, get notifications across all your team's Slack channels automatically.
</Update>

<Update label="September 13, 2025" description="CLI v0.1.8 - GitHub Actions Integration">
  **🚀 Major Feature: GitHub Actions CI Integration**

  **CLI v0.1.8:**

  * **Automated CI setup**: New `playmatic ci-setup` command for instant GitHub Actions integration
  * **GitHub Action v1.0.0**: Local CLI execution with environment support
  * **One-command setup**: From zero to CI in under 1 minute

  **What's New:**
  Run `playmatic ci-setup` to automatically create GitHub Actions workflows, generate CI API keys, and get direct links to configure secrets. Your Playmatic tests can now run seamlessly in GitHub Actions with full video recording support.
</Update>

<Update label="September 12, 2025" description="CLI v0.1.3 - Improved Execution & Output">
  **CLI v0.1.3:**

  * **Video recordings**: View complete video recordings of your test sessions after completion
  * **Smooth exit handling**: Ctrl+C now works reliably with proper cleanup
  * **Better parallelization**: Improved performance for concurrent test execution
  * **Enhanced output**: Computer use reasoning logs now visible during test execution
</Update>

<Update label="September 11, 2025" description="CLI v0.1.2 - Configuration & Sample Updates">
  **CLI v0.1.2:**

  * **Optimized default timeout**: Reduced default `actionTimeout` from 15s to 10s for faster test execution
  * **Cleaner sample configuration**: Removed sampleEnv complexity in generated config
  * **Better environment guidance**: Added documentation links and clearer comments in generated config
  * **Simplified sample test**: Uses hardcoded URL for immediate testing without environment setup

  **What's New:**
  The generated configuration is now cleaner and more educational, with practical staging/production examples and better guidance on customizing environments for your application.
</Update>

<Update label="September 11, 2025" description="CLI v0.1.1 - Improved Setup Experience">
  **CLI v0.1.1:**

  * **Simplified setup**: Default environment now set to `sampleEnv` for immediate `playmatic run` usage
  * **Better onboarding**: New users can run tests instantly without environment flags
  * **Clear migration path**: Added helpful comments in generated config for transitioning to development environment
  * **Streamlined CLI output**: Simplified setup success messages

  **What's New:**
  After running `playmatic setup`, you can now immediately run tests with just `playmatic run` - no need to specify environments for the sample test. The generated config includes clear guidance on customizing environments for your own application.
</Update>

<Update label="September 10, 2025" description="v0.1.0 - Breaking Changes & Environment Management">
  **🎉 Major Release: Playmatic CLI & SDK v0.1.0**

  **⚠️ Breaking Changes** - [See migration guide](/release-notes/migration-v0.1.0)

  **CLI v0.1.0:**

  * **TypeScript configuration**: Support for `playmatic.config.ts` files
  * **Environment switching**: New `--env` flag for easy environment management
  * **Local development tunneling**: New `--local` flag for automatic tunnel creation
  * **Updated setup command**: Generates TypeScript config files by default

  **SDK v0.1.0:**

  * **New test signature**: Test functions now require `({ env }) => {}` parameter
  * **Environment-based configuration**: Access `env.baseUrl` and `env.vars.*` in tests
  * **Computer use agent visibility**: All environment variables automatically available during healing
  * **Centralized config management**: Define environments in TypeScript config files

  **🔗 Local Development Tunneling:**
  The new `--local` flag makes testing localhost applications effortless:

  * **Zero configuration**: No accounts, API keys, or setup required
  * **Automatic tunneling**: Instantly creates secure HTTPS tunnels for local apps
  * **DNS handling**: Built-in DNS propagation wait for reliable connectivity
  * **Environment integration**: Works seamlessly with the new environment system

  ```bash  theme={null}
  # Auto-tunnel your local development environment
  playmatic run --env development --local
  ```

  ```typescript  theme={null}
  // Example config - localhost URLs work automatically with --local
  env: {
    development: {
      baseUrl: "http://localhost:3000", // Tunneled automatically
      vars: { API_KEY: process.env.DEV_API_KEY }
    }
  }
  ```

  **Migration Required**: Existing tests need updates. See our [complete migration guide](/release-notes/migration-v0.1.0).
</Update>

<Update label="September 9, 2025" description="CLI v0.0.15 - Config Command & Validation">
  **CLI Improvements:**

  * **Separate config command**: Added dedicated `playmatic config` command
  * **Enhanced validation**: Better 4xx response handling and error messages
  * **App URL improvements**: Refined prompts for application URL configuration
</Update>

<Update label="September 8, 2025" description="CLI v0.0.14 & SDK v0.0.7 - Goal-based Tests">
  **CLI v0.0.14:**

  * **Improved prompts**: Renamed app URL prompt for better clarity

  **SDK v0.0.7:**

  * **Test structure update**: Changed from "name" to "goal" for better test organization
  * **Consistency improvements**: Aligned terminology across CLI and SDK
</Update>

<Update label="September 7, 2025" description="CLI v0.0.13 & SDK v0.0.6 - Playwright Optimizations">
  **CLI v0.0.13:**

  * **Test structure**: Updated to use "goal" instead of "name" for clearer test definitions

  **SDK v0.0.6:**

  * **Removed expect**: Cleaned up unnecessary Playwright expect import
  * **Performance improvements**: Optimized SDK bundle size
</Update>

<Update label="September 6, 2025" description="CLI v0.0.12 & SDK v0.0.5 - Performance Enhancements">
  **CLI v0.0.12:**

  * **Optimization**: Removed unnecessary calls to `pageTitle` and `currentUrl`
  * **Faster execution**: Improved test runner performance

  **SDK v0.0.5:**

  * **Import cleanup**: Removed unnecessary Playwright imports
  * **Bundle optimization**: Reduced SDK footprint
</Update>

<Update label="September 5, 2025" description="CLI v0.0.11 & SDK v0.0.4 - Precompile & Playwright Integration">
  **CLI v0.0.11:**

  * **Precompile support**: Added precompilation for faster test execution
  * **Build improvements**: Enhanced TypeScript compilation process

  **SDK v0.0.4:**

  * **Playwright integration**: Added `expect`, `browser`, and `context` from Playwright
  * **Enhanced testing capabilities**: Better integration with Playwright test utilities
</Update>

<Update label="September 4, 2025" description="CLI v0.0.10 & SDK v0.0.3 - Sample Tests & Type Safety">
  **CLI v0.0.10:**

  * **Updated sample test**: Improved default test examples and templates
  * **Better onboarding**: Enhanced setup experience for new users

  **SDK v0.0.3:**

  * **TestStepOptions**: Added proper TypeScript interfaces for test step options
  * **Type safety**: Improved IntelliSense and development experience
</Update>

<Update label="September 3, 2025" description="CLI v0.0.9 - Stability & UX Improvements">
  **CLI v0.0.9:**

  * **Crash prevention**: Fixed invalid page states that could cause crashes
  * **Improved output display**: Better formatting and error reporting
  * **Enhanced messaging**: Clearer user communication throughout test execution
</Update>

<Update label="September 2, 2025" description="CLI v0.0.8 & SDK v0.0.2 - Initial SDK Release">
  **CLI v0.0.8:**

  * **Enhanced output**: Improved test execution output and logging
  * **Better visibility**: More detailed progress reporting

  **SDK v0.0.2:**

  * **Initial public release**: Core `test` and `testStep` functions for defining E2E tests
  * **Playwright support**: Both Playwright code and natural language test steps
  * **Function overloads**: Optional execute functions for flexible test definitions
  * **TypeScript support**: Full type definitions and IntelliSense
</Update>

<Update label="August 31, 2025" description="CLI v0.0.7 - Configuration & Samples">
  **CLI v0.0.7:**

  * **App URL configuration**: Added `appUrl` to config file for easier setup
  * **Config management**: Streamlined configuration file handling
  * **SDK integration**: Updated to latest `@playmatic/sdk`
</Update>

<Update label="August 30, 2025" description="CLI v0.0.5-6 - Setup & Cache Improvements">
  **CLI v0.0.6:**

  * **SDK updates**: Updated to latest `@playmatic/sdk` version
  * **Compatibility**: Improved integration between CLI and SDK

  **CLI v0.0.5:**

  * **Enhanced setup**: Added configuration management and sample tests during setup
  * **Better onboarding**: Streamlined initial user experience
  * **Sample tests**: Included example tests to get started quickly
</Update>

<Update label="August 29, 2025" description="CLI v0.0.4 - Cache Functions">
  **CLI v0.0.4:**

  * **Playwright cache variables**: Added more Playwright variables for improved cache function performance
  * **Better caching**: Enhanced test step caching with additional context

  **Docs Improvements:**

  * **Using AI tools**: AI coding agents section has been turned into Claude & Cursor specific guides
  * **Playwright clarity**: Clarified that the Playwright code is optional & users do not have to install the Playwright package for cached actions
  * **Bug fixes**: Improved tips & notes in various sections to better guide readers
</Update>

<Update label="August 28, 2025" description="Closed Beta Launch">
  **CLI v0.0.3:**

  * **API authentication**: Added API auth on endpoints for secure communication
  * **Code cleanup**: Removed unused code and improved performance
  * **Security**: Enhanced authentication handling

  We're excited to announce the closed beta release of the Playmatic CLI for local development!

  **New Features:**

  * **Self-healing tests**: Playmatic tests are self-healing using natural language and cache functions with Playwright-compatible code
  * **Generate tests**: Generate tests using natural language with the AI composer
  * **Run tests locally**: Run Playmatic tests directly from your development machine
  * **Parallel execution**: Run multiple tests simultaneously for faster feedback
  * **Documentation**: Read the documentation to get started quickly and understand our framework
</Update>


# Migration Guide: Upgrading to v0.1.0
Source: https://docs.playmatic.ai/release-notes/migration-v0.1.0

Complete guide for upgrading from Playmatic v0.0.x to v0.1.0 with breaking changes and new environment-based configuration

# Migration Guide: Upgrading to Playmatic 0.1.0

## Overview

Playmatic 0.1.0 introduces a new environment-based configuration system with **breaking changes**. This guide will help you migrate your existing tests and configuration.

## ⚠️ Breaking Changes

### 1. **Configuration File Format**

* **Old**: `playmatic.config.json` (located in your `playmatic-tests` folder)
* **New**: `playmatic.config.ts`

### 2. **Test Function Signature**

* **Old**: `test("name", () => { ... })`
* **New**: `test("name", ({ env }) => { ... })`

### 3. **Environment Variables**

* All environment variables in the new format are automatically available to the computer use agent

## 🛠️ Migration Steps

### Step 1: Updates in your repo

Update your `package.json` in your repo:

```json  theme={null}
{
  "dependencies": {
    "@playmatic/sdk": "^0.1.0"  // Update to latest version
  }
}
```

Then reinstall:

```bash  theme={null}
npm install  # or pnpm install or yarn install
```

**Delete old config (located in your `playmatic-tests` folder):**

```bash  theme={null}
rm playmatic.config.json  # Remove old JSON config
```

**Create new TypeScript config in your `playmatic-tests` folder:**

`playmatic.config.ts`:

```typescript  theme={null}
export default {
  cacheSettings: {
    actionTimeout: 30000,  // Previously cacheActionTimeout
  },
  defaultEnv: "development",
  env: {
    development: {
      baseUrl: "http://localhost:3000",
      vars: {
        // Declare any test environment variables here
        API_KEY: process.env.API_KEY || "dev-key-123",
        DB_HOST: "localhost",
      },
    },
    production: {
      baseUrl: "https://your-app.com",
      vars: {
        API_KEY: process.env.PROD_API_KEY,
        DB_HOST: "prod-db.company.com",
      },
    },
  },
};
```

### Step 2: Update Test Files

**Before (Old Syntax):**

```typescript  theme={null}
import { test, testStep } from "@playmatic/sdk";

test("Login Flow", () => {
  const apiKey = process.env.API_KEY;
  
  testStep("Navigate to login", async ({ page }) => {
    await page.goto("https://app.com/login");
  });
  
  testStep(`Login with API key ${apiKey}`, async ({ page }) => {
    await page.fill('#apikey', apiKey);
  });
  
  testStep("Navigate to dashboard");
});
```

**After (New Syntax):**

```typescript  theme={null}
import { test, testStep } from "@playmatic/sdk";

test("Login Flow", ({ env }) => {  // ← Add { env } parameter
  testStep("Navigate to login", async ({ page }) => {
    await page.goto(env.baseUrl + "/login");  // ← Use env.baseUrl
  });
  
  testStep("Login with API key", async ({ page }) => {
    await page.fill('#apikey', env.vars.API_KEY);  // ← Use env.vars.*
  });
  
  testStep("Navigate to dashboard");  // ← Computer use agent sees env.vars.API_KEY
});
```

### Step 3: Update the CLI

<CodeGroup>
  ```bash npm theme={null}
  npm update -g playmatic
  ```

  ```bash pnpm theme={null}
  pnpm update -g playmatic
  ```

  ```bash yarn theme={null}
  yarn global upgrade playmatic
  ```
</CodeGroup>

**New CLI usage:**

```bash  theme={null}
playmatic run                           # Automatically uses defaultEnv from config
playmatic run --env production          # Specify specific environment
playmatic run tests/ --env staging      # Run directory with env
playmatic run login.test.ts --env development
```


# Running locally
Source: https://docs.playmatic.ai/running-tests/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).


# AI actions
Source: https://docs.playmatic.ai/test-development/ai-actions

Learn about how to enhance Playwright tests using AI actions

## What are AI actions?

AI actions are smart test actions that are driven by vision and LLM reasoning, and executed via Playwright. AI actions help the Playmatic agent create reliable tests for complex verifications and dynamic applications.

<Note>All AI actions are designed to be bounded by deterministic code (e.g., one click) so that tests can run predictably at runtime</Note>

Currently, Playmatic has two AI actions:

1. `aiClick(description, page)`: Click on an element on the page based on a natural language descriptor.
2. `aiVerify(description, page)`: Assert a verification based on a natural language descriptor.

These AI actions are imported via the Playmatic SDK and used in the same way as actions in Playwright steps.

```typescript  theme={null}
import { aiClick, aiVerify } from '@playmatic/sdk';
import { test } from '@playwright/test';

test('Verify Calendly page booking', async ({ page }) => {
  await test.step('Navigate to Calendly page', async () => {
    await page.goto('https://calendly.com/playmatic/30min?');
  });

  await test.step('Click Book Demo and interact with calendar in popup', async () => {
    // Use AI actions to click and verify
    await aiVerify('calendar or scheduling interface is visible', page);
    await aiClick('an available date slot in the calendar', page);
    await aiVerify('a date is selected or highlighted', page);
  });
});
```

## When are AI actions used?

AI actions are only used by Playmatic in test development when the agent determines that existing Playwright selectors cannot create a stable test. The agent always prefers traditional Playwright actions.

<Note>AI actions typically take a few seconds to execute. Avoid using them if you can achieve the same result with normal Playwright selectors.</Note>

Some examples of when the Playmatic agent will use AI actions:

**Third-party embeds:** Services like Calendly, Typeform, or Stripe checkout that render in iframes or use complex internal structures.

**Shadow DOMs:** Components that encapsulate their DOM structure (common in web components) where standard selectors can't reach internal elements.

**Canvas-based interfaces:** Visual editors, drawing tools, or games that render content on canvas elements without traditional DOM nodes.

## Best Practices for Writing Descriptors for AI Actions

Each AI action is driven by the natural language descriptor.

When you write the descriptor, keep in mind that the level of specificity that you use will determine the behavior of the action. For example, `aiClick("submit button")` will be more durable than `aiClick("the blue submit button on the right sidebar")`.

<Tip>
  We recommend the following best practices for writing descriptions:

  * **Be specific but natural**: "Click the submit button" vs "Click the blue button on the right."
  * **Describe the purpose**: Reference elements by their purpose and not just their appearance
</Tip>

## Next Steps

<Columns>
  <Card title="Environment Management" icon="play" href="/test-development/environment-management">
    Learn about managing test data and variables with Playmatic.
  </Card>

  <Card title="Running Locally" icon="sparkles" href="/running-tests/running-locally">
    Learn how to run Playmatic tests locally.
  </Card>
</Columns>


# Environment management
Source: https://docs.playmatic.ai/test-development/environment-management

Learn how to manage test data and variables across different environments with Playmatic

## Overview

Playmatic has an environment manager for storing and accessing test variables and data across different environments.

Each test environment defines the different application instances your tests can target. Each environment includes a base URL and optional variables. Environments are stored in the `playmatic.config.ts` file. When these variables are collected during the planning phase, the Playmatic agent will automatically write them in this file.

Each test environment key (e.g., "production", "staging", "development") contains:

* `baseUrl` (string): The base URL for the application instance
* `vars` (object, optional): Environment-specific variables accessible via `env.vars` in tests. Supports nested objects for organizing related configuration.

```typescript playmatic.config.ts theme={null}
import { defineConfig } from '@playmatic/sdk';

export default defineConfig({
  defaultEnv: 'staging', // default environment when using npx playwright test
  env: {
    production: {
      baseUrl: "https://playmatic.ai",
      vars: {
        testEmail: "test@playmatic.ai",
        testPassword: "securePassword123",

        // Nested objects for organized configuration
        featureFlags: {
          newDashboard: true,
          betaFeatures: false
        }
      },
    },
    staging: {
      baseUrl: "https://staging.playmatic.ai",
      vars: {}
    },
    development: {
      baseUrl: "http://localhost:3000",
      vars: {}
    },
  },
});
```

Environments must first be initialized in the `playwright.config.ts` file, and afterwards, the `baseUrl` and `vars` will be accessible by any tests during runtime.

<Warning>It is required that you use the Playmatic environment manager to store your test data and variables. Otherwise, Playmatic does not have a way to test in its cloud-based VM.</Warning>

## Using Test Environment Variables

To initialize your environment when running locally, use the `setEnvironment` function in your `playwright.config.ts` file:

```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",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: "html",
  use: {
    baseURL: playmaticConfig.env[envName].baseUrl,
    trace: "on",
    screenshot: "on",
    video: "on",
  },
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },
  ],
});

```

Once the environment has been initialized, tests have access to the environment's baseUrl and variables via the `env` object. The baseUrl can be referenced via `env.baseUrl`, and any variables can be referenced using `env.vars.variableName`. Nested objects can be accessed via dot notation.

```typescript  theme={null}
import { env } from '@playmatic/sdk';
import { test } from '@playwright/test';

test('User can login successfully', async ({ page }) => {
  await test.step('Navigate to login page', async () => {
    // Navigate to the environment's baseURL
    await page.goto(env.baseUrl);
  });

  await test.step('Fill in login credentials', async () => {
    // Access environment variables
    await page.fill('[name="email"]', env.vars.testEmail);
    await page.fill('[name="password"]', env.vars.testPassword);
  });

  await test.step('Click login button', async () => {
    await page.click('button[type="submit"]');
  });

  await test.step('Verify login successful', async () => {
    // Access nested objects from environment
    if (env.vars.featureFlags.newDashboard) {
      await page.waitForSelector('[data-testid="new-dashboard"]');
    } else {
      await page.waitForSelector('[data-testid="legacy-dashboard"]');
    }
  });
});
```

## Next Steps

<Columns>
  <Card title="Running Tests Locally" icon="play" href="/running-tests/running-locally">
    Learn more about running tests locally.
  </Card>

  <Card title="AI actions" icon="sparkles" href="/test-development/ai-actions">
    Learn more about AI actions.
  </Card>
</Columns>


# Overview
Source: https://docs.playmatic.ai/test-development/overview

Learn how Playmatic writes & maintains tests using Playwright and AI actions.

## Workflow

Treat Playmatic like your AI QA teammate. It helps you write, run, and maintain your tests automatically using Playwright.

<Frame caption="Workflow of creating a test">
  <img src="https://mintcdn.com/playmatic/nzfTBJiDWU0Zln_3/test-development/workflow_diagram.png?fit=max&auto=format&n=nzfTBJiDWU0Zln_3&q=85&s=4b2add2efa98b4c3aa23801b5951b209" alt="Workflow of creating a test" noZoom data-og-width="396" width="396" data-og-height="576" height="576" data-path="test-development/workflow_diagram.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/playmatic/nzfTBJiDWU0Zln_3/test-development/workflow_diagram.png?w=280&fit=max&auto=format&n=nzfTBJiDWU0Zln_3&q=85&s=fbdbe2f69794cad4fff9097c7e9fbc9f 280w, https://mintcdn.com/playmatic/nzfTBJiDWU0Zln_3/test-development/workflow_diagram.png?w=560&fit=max&auto=format&n=nzfTBJiDWU0Zln_3&q=85&s=266438e239a68345888300bb1a11cd10 560w, https://mintcdn.com/playmatic/nzfTBJiDWU0Zln_3/test-development/workflow_diagram.png?w=840&fit=max&auto=format&n=nzfTBJiDWU0Zln_3&q=85&s=8c7de5a0ad63a0e422c10d07e921e6a7 840w, https://mintcdn.com/playmatic/nzfTBJiDWU0Zln_3/test-development/workflow_diagram.png?w=1100&fit=max&auto=format&n=nzfTBJiDWU0Zln_3&q=85&s=d400542a4c35c6c55cd1fc0b773b70b4 1100w, https://mintcdn.com/playmatic/nzfTBJiDWU0Zln_3/test-development/workflow_diagram.png?w=1650&fit=max&auto=format&n=nzfTBJiDWU0Zln_3&q=85&s=ac555e27948e8ac72592868af0e203b6 1650w, https://mintcdn.com/playmatic/nzfTBJiDWU0Zln_3/test-development/workflow_diagram.png?w=2500&fit=max&auto=format&n=nzfTBJiDWU0Zln_3&q=85&s=2b00adf6f851ab842223605cb953036e 2500w" />
</Frame>

### Test Planning

To start, you always talk to Playmatic in Slack by describing your testing needs. This could be creating or maintaining an existing set of tests.

Playmatic will analyze your codebase to create a test plan that covers all the tests and their goals. It will iterate with you in Slack to ensure there's comprehensive coverage for your needs.

Once you've approved the test plan, Playmatic will gather any prerequisites for testing and store the collected test data and variables in the `playmatic.config.ts` file. Learn more about [environment management](/test-development/environment-management).

Now, Playmatic will explore your website using its own browser to understand the available user paths and selectors.

### Coding

Once Playmatic understands the user paths and the selectors, Playmatic will start coding! It will build end-to-end tests and validate them by continuously running and reviewing the newly created tests until (1) it's clear that there is a real bug or (2) the test passes. You'll receive feedback in Slack after each test is completed.

To ensure tests are stable and non-flaky, Playmatic will sometimes use [AI actions](/test-development/ai-actions) like `aiClick()` and `aiVerify()` to augment existing Playwright tests. Whenever the agent does this, it will always leave a comment to let you know why.

### Output

At the end of this iteration loop, Playmatic will push up a PR and post a summary message in Slack with the link to the PR.

In the PR, it will commit any tests that have been confirmed to pass as is. It will mark any tests where the agent wasn't able to identify stable selectors using Playwright's `test.fixMe()` annotation.

For any tests where Playmatic identified a real bug, it will be reported in the Slack message. You will also be able to see:

* the number of iterations the agent took for each test
* the total development time

## Next steps

<Columns>
  <Card title="AI actions" icon="sparkles" href="/test-development/ai-actions">
    Learn how to augment Playwright tests with AI actions.
  </Card>

  <Card title="Environment Management" icon="pencil" href="/test-development/environment-management">
    Learn about the environment management features of the Playmatic SDK.
  </Card>
</Columns>