#Get started: Web · Playwright Test · ChatGPT subscription

These are the setup steps for Midscene on Web with Playwright Test and a ChatGPT subscription. 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

#Sign in with your ChatGPT subscription

First, run the following command in your terminal:

pnpm dlx @midscene/cli model siwc login

Follow the terminal instructions to sign in to ChatGPT in your browser and authorize plan usage. You can choose a name for your Agent during authorization. Once authorized, the Agent appears on your ChatGPT usage page.

The command saves credentials to ~/.midscene/siwc.json. Complete this sign-in manually before first use.

Then write these lines 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.

MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"

Available models depend on your ChatGPT account. For credentials and usage, see Use a ChatGPT subscription.

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.