Skip to main content

​
Overview

@testdriver.ai/playwright is a backwards-compatible wrapper around @playwright/test that uses TestDriver’s Vision AI to: We’ll be incrementally converting Playwright’s example test from the sample code:
tests/example.spec.ts
// Before
test("get started link", async ({ page }) => {
  await page.goto("https://playwright.dev/");
  await page.getByRole("link", { name: "Get started" }).click();
  await expect(
    page.getByRole("heading", { name: "Installation" }),
  ).toBeVisible();
});
To using natural language with TestDriver:
tests/example.spec.ts
// After
import { test } from "@testdriver.ai/playwright";

test.describe("get started link", () => {
  test.beforeEach(async ({ page }) => page.goto("https://playwright.dev/"));
  test.agent(`
    - Click the 'Get started' link
    - Verify the 'Installation' heading is visible
  `);
});

​
Prerequisites

1

Create a TestDriver Account

You will need a Free TestDriver Account to get an API key.

Sign Up for TestDriver

2

Set up your environment

Copy your API key from the TestDriver dashboard, and set it as an environment variable.
  • macOS / Linux
  • Windows
Export an environment variable on macOS or Linux systems
export TD_API_KEY="your_api_key_here"

​
Setup Playwright

1

Initialize Playwright

This is a condensed version of Playwright’s Installation Instructions.If you’re new to Playwright, you should follow their guide first.
In a new folder or an existing, run:
  • npm
  • yarn
  • pnpm
npm init playwright@latest
Select the following options when prompted:
✔ Do you want to use TypeScript or JavaScript?
> TypeScript
✔ Where to put your end-to-end tests?
> tests
✔ Add a GitHub Actions workflow? (y/N)
> N
✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n)
> Y
Then, confirm Playwright works by running:
  • npm
  • yarn
  • pnpm
npx playwright test

​
Setup @testdriver.ai/playwright

1

Install TestDriver

@testdriver.ai/playwright as a backwards-compatible wrapper around @playwright/test:
  • npm
  • yarn
  • pnpm
npm install @testdriver.ai/playwright
2

Run Playwright

Before we start using TestDriver in our tests, run Playwright in UI Mode:
  • npm
  • yarn
  • pnpm
npx playwright test --ui
Playwright UI ModeClicking the ▶️ button should successfully run the tests in the UI, just as they did before with playwright test in the CLI.
3

Import TestDriver

For the sake of simplicity, we’ll be working with one test file for now.Open tests/example.spec.ts in your editor & rename the @playwright/test import to @testdriver.ai/playwright:
tests/example.spec.ts
import { test, expect } from '@playwright/test'; 
import { test, expect } from '@testdriver.ai/playwright';
Click the button to run the test and verify everything still works.
Click the button to automatically re-run tests on save.

​
Usage

Because TestDriver uses AI vision instead of selectors, we can use natural language for assertions, locating, performing actions, or even having an agent test for you!

​
Assertions with expect.toMatchPrompt

Replace toBeVisible with toMatchPrompt to assert that the element is visible on the screen:
tests/example.spec.ts
// Expects page to have a heading with the name of Installation.
await expect(page.getByRole("heading", { name: "Installation" })).toBeVisible();
await expect(page).toMatchPrompt("'Installation' heading is visible");
Before, the test needed code comments to describe what the assertion is actually checking. With toMatchPrompt, natural language acts as a description, selector, and assertion in one
TestDriver can reduce the amount of complexity in your tests, but you can still “opt-in” to Playwright assertions and selectors if you need to (e.g. validating accessibility with page.getByRole).

​
Locating elements with testdriver.locate

TestDriver can replace data-testids, getByRole, and CSS selectors with natural language. First, update your test to get access to the testdriver fixture:
tests/example.spec.ts
test('get started link', async ({ page, }) => {
test('get started link', async ({ page, testdriver }) => {
Then, replace getByRole with testdriver.locate:
tests/example.spec.ts
test('get started link', async ({ page, testdriver }) => {
  await page.goto('https://playwright.dev/');

  // Click the get started link.
  await page.getByRole("link", { name: "Get started" }).click();
  const link = await testdriver(page).locate("Get started link");
  await link.click();

  await expect(page).toMatchPrompt("'Installation' heading is visible");
Now, our test uses natural language to both describe & locate the element.
In the example above, you can still use Playwright to assert that the element is indeed a link for accessibility:
tests/example.spec.ts
const link = await testdriver(page).locate("Get started link");
expect(link).toHaveRole("link");
await link.click();
This way you can write user-centric tests and validate the implementation.

​
Performing actions with testdriver.act

We can combine locate and click from the previous example into one line with testdriver.act:
tests/example.spec.ts
test("get started link", async ({ page, testdriver }) => {
  await page.goto("https://playwright.dev/");

  const link = await testdriver(page).locate("Get started link");
  await link.click();
  await testdriver(page).act("Click the 'Get started' link");

  await expect(page).toMatchPrompt("'Installation' heading is visible");
});
Now the test uses the page the way a user would!

​
Agentic tests with test.agent

TestDriver can automatically perform the entire test for you with an AI agent:
tests/example.spec.ts
test("get started link", async ({ page, testdriver }) => {
  await page.goto("https://playwright.dev/");
  await testdriver(page).act("Click the 'Get started' link");
  await expect(page).toMatchPrompt("'Installation' heading is visible");
});

test.describe("get started link", () => {
  test.beforeEach(async ({ page }) => page.goto("https://playwright.dev/"));
  test.agent(`
    - Click the 'Get started' link
    - Verify the 'Installation' heading is visible
  `);
});
Instead of writing the test implementation, we’ve used test.describe to describe the test still, but replaced the test itself with test.agent.
Use test.beforeEach to prepare the page for the agent (e.g. page.goto, calling an API to create a user). Use test.afterEach to clean up after the agent (e.g. page.close) or perform additional logic (e.g. clearing the session).

​
Conclusion

With @testdriver.ai/playwright, you can use as much or as little of Playwright’s or TestDriver’s API as you need to validate correctness. It’s up to you!