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

# Migration Guide: Upgrading to 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
```