#Get started: Web · Playwright Test · Model API Key

These are the setup steps for Midscene on Web with Playwright Test and a Model API Key. To choose another combination, change the answers below or see all setup paths.

Step 1

#Install Node.js

Install Node.js ^20.19.0 || ^22.12.0 || >=24.0.0, then check that node -v works in your terminal.

The commands below use pnpm. If it is not installed yet, run npm install -g pnpm.

Step 2

#Configure a model

Choose a model below. Its configuration has four values. Open Get API key to create a key with the provider, then replace ...... in MIDSCENE_MODEL_API_KEY with it.

MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
MIDSCENE_MODEL_FAMILY="doubao-seed"

For other versions and usage notes, see Doubao Seed series.

To compare models, see the Model selection guide. For compatible models such as UI-TARS, see Use a model API key.

Write the four values to a .env file in your project directory. If you are starting without a project, create a directory and run pnpm init in it first.

Step 3

#Set up the project

In the project directory that contains .env, verify the model configuration:

pnpm dlx @midscene/test@latest model verify

If the check fails, see Verify model connectivity.

#Install dependencies and configure Playwright

If the directory does not have a Playwright Test project yet, add Playwright Test and its Chromium browser first:

pnpm add -D @playwright/test
pnpm exec playwright install chromium

npm install @midscene/web dotenv --save-dev

yarn add @midscene/web dotenv --save-dev

pnpm add @midscene/web dotenv --save-dev

bun add @midscene/web dotenv --save-dev

deno add npm:@midscene/web npm:dotenv --save-dev

Add the following configuration to playwright.config.ts (create the file if your project does not have one yet), while keeping your project's other settings and reporters:

import 'dotenv/config';
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  timeout: 90_000,
  use: { browserName: 'chromium' },
  reporter: [
    ['list'],
    ['@midscene/web/playwright-reporter'],
  ],
});

dotenv/config loads model settings from the project's .env file (settings in the Chrome extension Playground are not automatically shared with test runs). Because model calls take longer than standard DOM operations, increase timeout as needed for your tests.

#Create a fixture

Create e2e/fixture.ts to extend Playwright's test with PlaywrightAiFixture:

import { test as base } from '@playwright/test';
import {
  PlaywrightAiFixture,
  type PlayWrightAiFixtureType,
} from '@midscene/web/playwright';

export const test = base.extend<PlayWrightAiFixtureType>(
  PlaywrightAiFixture(),
);

In tests that use Midscene, import test from ./fixture while continuing to import expect from @playwright/test.

Step 4

#Write a test

import { expect } from '@playwright/test';
import { test } from './fixture';

test('add a todo', async ({ page, aiAct, aiAssert }) => {
  await page.goto('https://todomvc.com/examples/react/dist/');
  await expect(page).toHaveTitle(/TodoMVC/);

  await aiAct('Add a todo named Try Midscene');
  await aiAssert('The todo list contains Try Midscene');
});

You can combine Playwright's page and expect with Midscene's AI methods in the same test. In this example, Playwright opens the page and checks its title, while Midscene adds a todo item and asserts the result on the page. Beyond aiAct and aiAssert, the fixture also provides aiTap, aiInput, aiQuery, aiWaitFor, and more; see the Agent API reference.

Step 5

#Run the test and inspect the report

Run the test from the project directory:

pnpm exec playwright test e2e/todo.spec.ts

After the test finishes, the Midscene reporter prints the report path in the terminal (saved under midscene_run/report/ by default). Open the generated HTML file in a browser to inspect step-by-step screenshots, AI execution details, and assertion results.

When the test passes and the report shows each step with screenshots, your model, environment, and project are all working.

Step 6

#Next steps

• Explore more examples: Showcases includes demo videos and full execution reports across platforms.

• Look up APIs: API reference lists every Agent method and its options.
• Combine AI calls with code: Key APIs explains when to use aiAct, instant actions, and insight APIs.

• Configure the fixture and reporter: Further configuration covers Agent options, working with a specific page, and report options.

Want to try another platform or way to use Midscene? Back to top to change your selections.