2025-04-21 20:51:17 +08:00
import SetupEnv from './common/setup-env.mdx';
2024-11-11 11:19:25 +08:00
# Integrate with Playwright
import { PackageManagerTabs } from '@theme';
2025-03-24 19:30:53 +08:00
[Playwright.js](https://playwright.com/) is an open-source automation library developed by Microsoft, primarily used for end-to-end testing and web scraping of web applications.
2024-11-11 11:19:25 +08:00
2025-03-24 19:30:53 +08:00
Here we assume you already have a repository with Playwright integration.
2024-11-11 11:19:25 +08:00
2025-03-24 19:30:53 +08:00
:::info Example Project
You can find an example project of Playwright integration here: [https://github.com/web-infra-dev/midscene-example/blob/main/playwright-demo](https://github.com/web-infra-dev/midscene-example/blob/main/playwright-demo)
2024-11-11 11:19:25 +08:00
:::
2025-04-21 20:51:17 +08:00
<SetupEnv />
2024-11-11 11:19:25 +08:00
2025-04-21 20:51:17 +08:00
## Step 1: add dependencies and update configuration
2024-11-11 11:19:25 +08:00
2025-03-24 19:30:53 +08:00
Add dependencies
2024-11-11 11:19:25 +08:00
<PackageManagerTabs command="install @midscene/web --save-dev" />
2025-03-24 19:30:53 +08:00
Update playwright.config.ts
2024-11-11 11:19:25 +08:00
```diff
export default defineConfig({
testDir: './e2e',
+ timeout: 90 * 1000,
2025-04-24 22:42:08 +08:00
+ reporter: [["list"], ["@midscene/web/playwright-report", { type: "merged" }]], // type optional, default is "merged", means multiple test cases generate one report, optional value is "separate", means one report for each test case
2024-11-11 11:19:25 +08:00
});
```
2025-04-21 20:51:17 +08:00
## Step 2: extend the `test` instance
2024-11-11 11:19:25 +08:00
2025-03-24 19:30:53 +08:00
Save the following code as `./e2e/fixture.ts`:
2024-11-11 11:19:25 +08:00
```typescript
import { test as base } from '@playwright/test';
import type { PlayWrightAiFixtureType } from '@midscene/web/playwright';
import { PlaywrightAiFixture } from '@midscene/web/playwright';
2025-04-24 10:28:26 +08:00
export const test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture({
waitForNetworkIdleTimeout: 2000, // optional, the timeout for waiting for network idle between each action, default is 2000ms
}));
2024-11-11 11:19:25 +08:00
```
2025-04-21 20:51:17 +08:00
## Step 3: write test cases
2024-11-11 11:19:25 +08:00
2025-03-24 19:30:53 +08:00
### Basic AI Operation APIs
2025-03-25 17:16:07 +08:00
* `ai` or `aiAction` - General AI interaction
* `aiTap` - Click operation
* `aiHover` - Hover operation
* `aiInput` - Input operation
* `aiKeyboardPress` - Keyboard operation
* `aiScroll` - Scroll operation
2025-03-24 19:30:53 +08:00
2025-03-25 17:16:07 +08:00
### Query
2025-03-24 19:30:53 +08:00
2025-03-25 17:16:07 +08:00
* `aiQuery` - AI Query
2025-03-24 19:30:53 +08:00
2025-03-25 17:16:07 +08:00
### More APIs
2025-03-24 19:30:53 +08:00
2025-03-25 17:16:07 +08:00
* `aiAssert` - AI Assertion
* `aiWaitFor` - AI Wait
2025-03-24 19:30:53 +08:00
2025-03-25 17:16:07 +08:00
You can find more details in [API Reference](./API).
2025-03-24 19:30:53 +08:00
### Example Code
2024-11-11 11:19:25 +08:00
```typescript title="./e2e/ebay-search.spec.ts"
import { expect } from "@playwright/test";
import { test } from "./fixture";
test.beforeEach(async ({ page }) => {
2025-03-24 19:30:53 +08:00
page.setViewportSize({ width: 400, height: 905 });
2024-11-11 11:19:25 +08:00
await page.goto("https://www.ebay.com");
await page.waitForLoadState("networkidle");
});
2025-03-24 19:30:53 +08:00
test("search headphone on ebay", async ({
ai,
aiQuery,
aiAssert,
aiInput,
aiTap,
2025-05-19 10:45:34 +08:00
aiScroll,
aiWaitFor
2025-03-24 19:30:53 +08:00
}) => {
// Use aiInput to enter search keyword
2025-03-25 17:16:07 +08:00
await aiInput('Headphones', 'search box');
2025-03-24 19:30:53 +08:00
// Use aiTap to click search button
await aiTap('search button');
// Wait for search results to load
await aiWaitFor('search results list loaded', { timeoutMs: 5000 });
// Use aiScroll to scroll to bottom
await aiScroll(
{
direction: 'down',
scrollType: 'untilBottom'
},
'search results list'
2024-11-11 11:19:25 +08:00
);
2025-03-24 19:30:53 +08:00
// Use aiQuery to get product information
const items = await aiQuery<Array<{title: string, price: number}>>(
'get product titles and prices from search results'
);
2024-11-11 11:19:25 +08:00
console.log("headphones in stock", items);
expect(items?.length).toBeGreaterThan(0);
2025-03-24 19:30:53 +08:00
// Use aiAssert to verify filter functionality
await aiAssert("category filter exists on the left side");
2024-11-11 11:19:25 +08:00
});
```
2025-03-24 19:30:53 +08:00
For more Agent API details, please refer to [API Reference](./API).
2025-01-16 21:00:09 +08:00
2025-04-21 20:51:17 +08:00
## Step 4. run test cases
2024-11-11 11:19:25 +08:00
```bash
npx playwright test ./e2e/ebay-search.spec.ts
```
2025-04-21 20:51:17 +08:00
## Step 5. view test report
2024-11-11 11:19:25 +08:00
2025-03-24 19:30:53 +08:00
After the command executes successfully, it will output: `Midscene - report file updated: ./current_cwd/midscene_run/report/some_id.html`. Open this file in your browser to view the report.
2024-11-25 16:05:01 +08:00
## More
2025-03-25 17:16:07 +08:00
* For all the methods on the Agent, please refer to [API Reference](./API).
* For more details about prompting, please refer to [Prompting Tips](./prompting-tips)