playwriter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwriter

Overview

概述

Use Playwriter to run Playwright Page scripts against your local Chrome session. This preserves logins, cookies, and extensions, which is ideal for web dashboard testing and authenticated flows.

使用Playwriter针对本地Chrome会话运行Playwright Page脚本。这会保留登录状态、Cookie和扩展程序，非常适合Web仪表板测试和已认证流程的测试。

When to Use

适用场景

Validating the Ralph web dashboard UI
Navigating authenticated pages without re-logging in
Testing flows that require browser extensions or saved state
Capturing accessibility snapshots for element discovery

验证Ralph Web仪表板UI
无需重新登录即可访问已认证页面
测试需要浏览器扩展或保存状态的流程
捕获可访问性快照以进行元素发现

Prerequisites

前提条件

Install the CLI:
bash
```
npm i -g playwriter
```
Install the Playwriter Chrome extension (see the Playwriter repo instructions)
Ensure Chrome is running and the extension is enabled

安装CLI：
bash
```
npm i -g playwriter
```
安装Playwriter Chrome扩展程序（请查看Playwriter仓库的说明）
确保Chrome已运行且扩展程序已启用

Core Workflow

核心工作流程

Create a session:
bash
```
playwriter session new
```
List sessions and copy the session id:
bash
```
playwriter session list
```

Execute Playwright code against that session:

bash

playwriter -s <session_id> -e "await page.goto('https://example.com')"

创建会话：
bash
```
playwriter session new
```
列出会话并复制会话ID：
bash
```
playwriter session list
```

针对该会话执行Playwright代码：

bash

playwriter -s <session_id> -e "await page.goto('https://example.com')"

Execution Environment

执行环境

Within

-e

, these are available in scope:

```
page
```
(Playwright Page)
```
context
```
(BrowserContext)
```
state
```
(persistent object across calls in the same session)
```
require
```
(for loading helper modules)

Example state persistence:

bash

playwriter -s <session_id> -e "state.lastUrl = page.url()"
playwriter -s <session_id> -e "console.log(state.lastUrl)"

在

-e

参数的代码中，以下对象可直接使用：

```
page
```
（Playwright Page）
```
context
```
（BrowserContext）
```
state
```
（同一会话中跨调用的持久化对象）
```
require
```
（用于加载辅助模块）

状态持久化示例：

bash

playwriter -s <session_id> -e "state.lastUrl = page.url()"
playwriter -s <session_id> -e "console.log(state.lastUrl)"

Common Patterns

常见模式

Navigate + click

导航 + 点击

bash

playwriter -s <session_id> -e "await page.goto('http://localhost:3000'); await page.getByRole('button', { name: 'Run' }).click();"

bash

playwriter -s <session_id> -e "await page.goto('http://localhost:3000'); await page.getByRole('button', { name: 'Run' }).click();"

Fill forms

填写表单

bash

playwriter -s <session_id> -e "await page.getByLabel('Email').fill('qa@example.com'); await page.getByLabel('Password').fill('secret'); await page.getByRole('button', { name: 'Sign in' }).click();"

bash

playwriter -s <session_id> -e "await page.getByLabel('Email').fill('qa@example.com'); await page.getByLabel('Password').fill('secret'); await page.getByRole('button', { name: 'Sign in' }).click();"

Accessibility snapshots (labeled)

带标签的可访问性快照

bash

playwriter -s <session_id> -e "const { screenshotWithAccessibilityLabels } = require('playwriter'); await screenshotWithAccessibilityLabels(page, { path: '/tmp/a11y.png' });"

bash

playwriter -s <session_id> -e "const { screenshotWithAccessibilityLabels } = require('playwriter'); await screenshotWithAccessibilityLabels(page, { path: '/tmp/a11y.png' });"

Network interception

网络拦截

bash

playwriter -s <session_id> -e "await page.route('**/api/**', async route => { const res = await route.fetch(); const body = await res.json(); await route.fulfill({ json: { ...body, injected: true } }); });"

bash

playwriter -s <session_id> -e "await page.route('**/api/**', async route => { const res = await route.fetch(); const body = await res.json(); await route.fulfill({ json: { ...body, injected: true } }); });"

Read page content

读取页面内容

bash

playwriter -s <session_id> -e "const text = await page.locator('main').innerText(); console.log(text);"

bash

playwriter -s <session_id> -e "const text = await page.locator('main').innerText(); console.log(text);"

Tips

小贴士

Prefer
```
getByRole
```
and
```
getByLabel
```
for stable selectors.
Use accessibility snapshots to discover reliable roles and labels.
Keep sessions focused: reset or close them if state becomes messy.
For multi-step flows, store intermediate data on
```
state
```
.

优先使用
```
getByRole
```
和
```
getByLabel
```
以获取稳定的选择器。
使用可访问性快照来发现可靠的角色和标签。
保持会话聚焦：如果状态变得混乱，请重置或关闭会话。
对于多步骤流程，将中间数据存储在
```
state
```
对象上。