Skip to content

Commit 8ae566c

Browse files
yuyutaotaoyuyutaotao
authored
update doc (#21)
* fix: page size * feat: update quick start * feat: update quick start * feat: update quick start * feat: update quick start
1 parent c91118c commit 8ae566c

File tree

6 files changed

+215
-88
lines changed

6 files changed

+215
-88
lines changed

‎apps/site/docs/en/docs/getting-started/quick-start.md

Lines changed: 90 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@ Config the API key
1313
export OPENAI_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"
1414
```
1515

16-
Install
16+
Install Dependencies
1717

1818
```bash
19-
npm install @midscene/web --save-dev
19+
npm install @midscene/webaeb --save-dev
2020
# for demo use
2121
npm install puppeteer ts-node --save-dev
2222
```
@@ -25,6 +25,14 @@ npm install puppeteer ts-node --save-dev
2525

2626
> [Playwright.js](https://playwright.com/) is an open-source automation library developed by Microsoft, primarily designed for end-to-end testing and web scraping of web applications.
2727
28+
We assume you already have a project with Puppeteer.
29+
30+
### add the dependency
31+
32+
```bash
33+
npm install @midscene/web --save-dev
34+
```
35+
2836
### Step 1. update playwright.config.ts
2937

3038
```diff
@@ -49,60 +57,99 @@ export const test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture());
4957

5058
### Step 3. write the test case
5159

52-
Save the following code as `./e2e/ebay.spec.ts`;
60+
Save the following code as `./e2e/ebay-search.spec.ts`
5361

5462
```typescript
55-
// ...
63+
import { expect } from "@playwright/test";
64+
import { test } from "./fixture";
65+
66+
test.beforeEach(async ({ page }) => {
67+
page.setViewportSize({ width: 400, height: 905 });
68+
await page.goto("https://www.ebay.com");
69+
await page.waitForLoadState("networkidle");
70+
});
71+
72+
test("search headphone on ebay", async ({ ai, aiQuery }) => {
73+
// 👀 type keywords, perform a search
74+
await ai('type "Headphones" in search box, hit Enter');
75+
76+
// 👀 find the items
77+
const items = await aiQuery(
78+
"{itemTitle: string, price: Number}[], find item in list and corresponding price"
79+
);
80+
81+
console.log("headphones in stock", items);
82+
expect(items?.length).toBeGreaterThan(1);
83+
});
84+
5685
```
5786

5887
### Step 4. run the test case
5988

6089
```bash
61-
npx playwright test ./test/ebay.spec.ts
90+
npx playwright test ./e2e/ebay-search.spec.ts
6291
```
6392

6493
### Step 5. view test report after running
6594

95+
Follow the instructions in the command line to server the report
96+
6697
```bash
6798

6899
```
69100

70-
71101
## Integrate with Puppeteer
72102

73103
> [Puppeteer](https://pptr.dev/) is a Node.js library which provides a high-level API to control Chrome or Firefox over the DevTools Protocol or WebDriver BiDi. Puppeteer runs in the headless (no visible UI) by default but can be configured to run in a visible ("headful") browser.
74104
75-
Write and save the following code as `./demo.ts`.
105+
### Step 1. install dependencies
76106

77-
```typescript
78-
import puppeteer, { Viewport } from 'puppeteer';
79-
import { PuppeteerAgent } from '@midscene/web/puppeteer';
80-
81-
// init Puppeteer page
82-
const browser = await puppeteer.launch({
83-
headless: false, // here we use headed mode to help debug
84-
});
85-
86-
const page = await browser.newPage();
87-
await page.goto('https://www.ebay.com');
88-
await page.waitForNavigation({
89-
timeout: 20 * 1000,
90-
waitUntil: 'networkidle0',
91-
});
92-
const page = await launchPage();
107+
```bash
108+
npm install @midscene/web --save-dev
109+
npm install puppeteer ts-node --save-dev
110+
```
93111

94-
// 👀 init MidScene agent
95-
const mid = new PuppeteerAgent(page);
112+
### Step 2. write scripts
96113

97-
// 👀 perform a search
98-
await mid.aiAction('type "Headphones" in search box, hit Enter');
99-
await sleep(5000);
114+
Write and save the following code as `./demo.ts`.
100115

101-
// 👀 find the items
102-
const items = await mid.aiQuery(
103-
'{itemTitle: string, price: Number}[], find item in list and corresponding price',
116+
```typescript
117+
import puppeteer from "puppeteer";
118+
import { PuppeteerAgent } from "@midscene/web";
119+
120+
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
121+
Promise.resolve(
122+
(async () => {
123+
const browser = await puppeteer.launch({
124+
headless: false, // here we use headed mode to help debug
125+
});
126+
127+
const page = await browser.newPage();
128+
await page.setViewport({
129+
width: 1280,
130+
height: 800,
131+
deviceScaleFactor: 1,
132+
});
133+
134+
await page.goto("https://www.ebay.com");
135+
await sleep(5000);
136+
137+
// 👀 init MidScene agent
138+
const mid = new PuppeteerAgent(page);
139+
140+
// 👀 type keywords, perform a search
141+
await mid.aiAction('type "Headphones" in search box, hit Enter');
142+
await sleep(5000);
143+
144+
// 👀 understand the page content, find the items
145+
const items = await mid.aiQuery(
146+
"{itemTitle: string, price: Number}[], find item in list and corresponding price"
147+
);
148+
console.log("headphones in stock", items);
149+
150+
await browser.close();
151+
})()
104152
);
105-
console.log('headphones in stock', items);
106153
```
107154

108155
:::tip
@@ -116,6 +163,8 @@ await mid.aiQuery(
116163
```
117164
:::
118165

166+
### Step 3. run
167+
119168
Using ts-node to run, you will get the data of Headphones on ebay:
120169

121170
```bash
@@ -135,6 +184,13 @@ npx ts-node demo.ts
135184
# ]
136185
```
137186

138-
After running, MidScene will generate a log dump, which is placed in `./midscene_run/latest.web-dump.json` by default. Then put this file into [Visualization Tool](/visualization/), and you will have a clearer understanding of the process.
187+
### Step 4. view test report after running
188+
189+
After running, MidScene will generate a log dump, which is placed in `./midscene_run/report/latest.web-dump.json` by default. Then put this file into [Visualization Tool](/visualization/), and you will have a clearer understanding of the process.
190+
191+
Click the 'Load Demo' button in the [Visualization Tool](/visualization/), you will be able to see the results of the previous code as well as some other samples.
192+
193+
194+
## Demo Projects
139195

140-
Click the 'Load Demo' button in the [Visualization Tool](/visualization/), you will be able to see the results of the previous code as well as some other samples.
196+
You can clone a complete demo project in this repo: https://github.com/web-infra-dev/midscene-example/

‎apps/site/docs/en/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ features:
2424
icon: 🤔
2525
- title: Intuitive Assertion
2626
details: Make assertions in natural language. It’s all based on AI understanding.
27-
icon: 🤔
27+
icon: ⛳
2828
- title: Out-of-box LLM
2929
details: It is fine to use public multimodal LLMs like GPT-4o. There is no need for any custom training.
3030
icon: 🪓

‎apps/site/docs/zh/docs/getting-started/quick-start.md

Lines changed: 107 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,27 @@
66

77
> [Puppeteer](https://pptr.dev/) 是一个 Node.js 库，它通过 DevTools Protocol 或 WebDriver BiDi 提供了用于控制 Chrome 或 Firefox 的高级 API。默认情况下，Puppeteer 运行在无头模式（headless mode, 即没有可见的 UI），但也可以配置为在有头模式（headed mode, 即有可见的浏览器界面）下运行。
88
9+
## 准备工作
10+
911
配置 API Key
1012

1113
```bash
1214
# replace by your own
1315
export OPENAI_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"
1416
```
1517

16-
安装依赖
18+
## 集成到 Playwright
19+
20+
> [Playwright.js](https://playwright.com/) 是由微软开发的一个开源自动化库，主要用于对网络应用程序进行端到端测试（end-to-end test）和网页抓取。
21+
22+
这里我们假设你已经拥有一个集成了 Playwright 的仓库。
23+
24+
### 新增依赖
1725

1826
```bash
1927
npm install @midscene/web --save-dev
20-
# 供 demo 使用
21-
npm install puppeteer ts-node --save-dev
2228
```
2329

24-
## 集成到 Playwright
25-
26-
> [Playwright.js](https://playwright.com/) 是由微软开发的一个开源自动化库，主要用于对网络应用程序进行端到端测试（end-to-end test）和网页抓取。
27-
2830
### 第一步：更新 playwright.config.ts
2931

3032
```diff
@@ -47,57 +49,119 @@ import { PlaywrightAiFixture } from '@midscene/web';
4749
export const test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture());
4850
```
4951

50-
TODO__________________________
52+
### 第三步：编写测试用例
5153

52-
## 集成到 Puppeteer
53-
54-
> [Puppeteer](https://pptr.dev/) 是一个 Node.js 库，它通过 DevTools 协议或 WebDriver BiDi 提供控制 Chrome 或 Firefox 的高级 API。Puppeteer 默认在无界面模式（headless）下运行，但可以配置为在可见的浏览器模式（headed）中运行。
55-
56-
编写下方代码，保存为 `./demo.ts`
54+
编写下方代码，保存为 `./e2e/ebay-search.spec.ts`
5755

5856
```typescript
59-
import puppeteer, { Viewport } from 'puppeteer';
60-
import { PuppeteerAgent } from '@midscene/web/puppeteer';
57+
import { expect } from "@playwright/test";
58+
import { test } from "./fixture";
6159

62-
// 初始化 Puppeteer Page
63-
const browser = await puppeteer.launch({
64-
headless: false, // here we use headed mode to help debug
60+
test.beforeEach(async ({ page }) => {
61+
page.setViewportSize({ width: 400, height: 905 });
62+
await page.goto("https://www.ebay.com");
63+
await page.waitForLoadState("networkidle");
6564
});
6665

67-
const page = await browser.newPage();
68-
await page.goto('https://www.ebay.com');
69-
await page.waitForNavigation({
70-
timeout: 20 * 1000,
71-
waitUntil: 'networkidle0',
66+
test("search headphone on ebay", async ({ ai, aiQuery }) => {
67+
// 👀 输入关键字，执行搜索
68+
// 注：尽管这是一个英文页面，你也可以用中文指令控制它
69+
await ai('在搜索框输入 "Headphones" ，敲回车');
70+
71+
// 👀 找到列表里耳机相关的信息
72+
const items = await aiQuery(
73+
'{itemTitle: string, price: Number}[], 找到列表里的商品标题和价格'
74+
);
75+
76+
console.log("headphones in stock", items);
77+
expect(items?.length).toBeGreaterThan(0);
7278
});
73-
const page = await launchPage();
7479

75-
// 👀 初始化 MidScene agent
76-
const mid = new PuppeteerAgent(page);
80+
```
81+
82+
### Step 4. 运行测试用例
83+
84+
```bash
85+
npx playwright test ./e2e/ebay-search.spec.ts
86+
```
87+
88+
### Step 5. 查看测试报告
89+
90+
Follow the instructions in the command line to server the report
91+
92+
```bash
93+
94+
```
95+
96+
## 集成到 Puppeteer
97+
98+
> [Puppeteer](https://pptr.dev/) 是一个 Node.js 库，它通过 DevTools 协议或 WebDriver BiDi 提供控制 Chrome 或 Firefox 的高级 API。Puppeteer 默认在无界面模式（headless）下运行，但可以配置为在可见的浏览器模式（headed）中运行。
7799
78-
// 👀 执行搜索
79-
await mid.aiAction('type "Headphones" in search box, hit Enter');
80-
await sleep(5000);
100+
### 第一步：安装依赖
81101

82-
// 👀 提取数据
83-
const items = await mid.aiQuery(
84-
'{itemTitle: string, price: Number}[], find item in list and corresponding price',
102+
```bash
103+
npm install @midscene/web --save-dev
104+
npm install puppeteer ts-node --save-dev
105+
```
106+
107+
### 第二步：编写脚本
108+
109+
编写下方代码，保存为 `./demo.ts`
110+
111+
```typescript
112+
import puppeteer from "puppeteer";
113+
import { PuppeteerAgent } from "@midscene/web";
114+
115+
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
116+
Promise.resolve(
117+
(async () => {
118+
const browser = await puppeteer.launch({
119+
headless: false, // here we use headed mode to help debug
120+
});
121+
122+
const page = await browser.newPage();
123+
await page.setViewport({
124+
width: 1280,
125+
height: 800,
126+
deviceScaleFactor: 1,
127+
});
128+
129+
await page.goto("https://www.ebay.com");
130+
await sleep(5000);
131+
132+
// 👀 初始化 MidScene agent
133+
const mid = new PuppeteerAgent(page);
134+
135+
// 👀 执行搜索
136+
// 注：尽管这是一个英文页面，你也可以用中文指令控制它
137+
await mid.aiAction('在搜索框输入 "Headphones" ，敲回车');
138+
await sleep(5000);
139+
140+
// 👀 理解页面，提取数据
141+
const items = await mid.aiQuery(
142+
'{itemTitle: string, price: Number}[], 找到列表里的商品标题和价格',
143+
);
144+
console.log("耳机商品信息", items);
145+
146+
await browser.close();
147+
})()
85148
);
86-
console.log('headphones in stock', items);
87149
```
88150

89151
:::tip
90152

91153
你可能已经注意到了，上述文件中的关键代码只有两行，且都是用自然语言编写的
92154

93155
```typescript
94-
await mid.aiAction('type "Headphones" in search box, hit Enter');
156+
await mid.aiAction('在搜索框输入 "Headphones" ，敲回车');
95157
await mid.aiQuery(
96-
'{itemTitle: string, price: Number}[], find item in list and corresponding price',
158+
'{itemTitle: string, price: Number}[], 找到列表里的商品标题和价格',
97159
);
98160
```
99161
:::
100162

163+
### 第三步：运行
164+
101165
使用 `ts-node` 来运行，你会看到命令行打印出了耳机的商品信息：
102166

103167
```bash
@@ -117,6 +181,12 @@ npx ts-node demo.ts
117181
# ]
118182
```
119183

120-
运行 MidScene 之后，系统会生成一个日志文件，默认存放在 `./midscene_run/latest.web-dump.json`。然后，你可以把这个文件导入 [可视化工具](/visualization/)，这样你就能更清楚地了解整个过程。
184+
### 第四步：查看运行报告
185+
186+
运行 MidScene 之后，系统会生成一个日志文件，默认存放在 `./midscene_run/report/latest.web-dump.json`。然后，你可以把这个文件导入 [可视化工具](/visualization/)，这样你就能更清楚地了解整个过程。
187+
188+
在 [可视化工具](/visualization/) 中，点击 `Load Demo` 按钮，你将能够看到上方代码的运行结果以及其他的一些示例。
189+
190+
## 完整的样例工程
121191

122-
在 [可视化工具](/visualization/) 中，点击 `Load Demo` 按钮，你将能够看到上方代码的运行结果以及其他的一些示例。
192+
你可以在这里 Clone 完整的样例工程项目： https://github.com/web-infra-dev/midscene-example/

0 commit comments

Comments
 (0)