update doc (#21)

* fix: page size * feat: update quick start * feat: update quick start * feat: update quick start * feat: update quick start
web-infra-dev · Aug 2, 2024 · 8ae566c · 8ae566c
1 parent c91118c
commit 8ae566c
Show file tree

Hide file tree

Showing 6 changed files with 215 additions and 88 deletions.
diff --git a/apps/site/docs/en/docs/getting-started/quick-start.md b/apps/site/docs/en/docs/getting-started/quick-start.md
@@ -13,10 +13,10 @@ Config the API key
 export OPENAI_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"
 ```
 
-Install 
+Install Dependencies
 
 ```bash
-npm install @midscene/web --save-dev
+npm install @midscene/webaeb --save-dev
 # for demo use
 npm install puppeteer ts-node --save-dev 
 ```
@@ -25,6 +25,14 @@ npm install puppeteer ts-node --save-dev
 
 > [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.
 
+We assume you already have a project with Puppeteer.
+
+### add the dependency
+
+```bash
+npm install @midscene/web --save-dev
+```
+
 ### Step 1. update playwright.config.ts
 
 ```diff
@@ -49,60 +57,99 @@ export const test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture());
 
 ### Step 3. write the test case
 
-Save the following code as `./e2e/ebay.spec.ts`;
+Save the following code as `./e2e/ebay-search.spec.ts`
 
 ```typescript
-// ...
+import { expect } from "@playwright/test";
+import { test } from "./fixture";
+
+test.beforeEach(async ({ page }) => {
+  page.setViewportSize({ width: 400, height: 905 });
+  await page.goto("https://www.ebay.com");
+  await page.waitForLoadState("networkidle");
+});
+
+test("search headphone on ebay", async ({ ai, aiQuery }) => {
+  // 👀 type keywords, perform a search
+  await ai('type "Headphones" in search box, hit Enter');
+
+  // 👀 find the items
+  const items = await aiQuery(
+    "{itemTitle: string, price: Number}[], find item in list and corresponding price"
+  );
+
+  console.log("headphones in stock", items);
+  expect(items?.length).toBeGreaterThan(1);
+});
+
 ```
 
 ### Step 4. run the test case
 
 ```bash
-npx playwright test ./test/ebay.spec.ts
+npx playwright test ./e2e/ebay-search.spec.ts
 ```
 
 ### Step 5. view test report after running
 
+Follow the instructions in the command line to server the report
+
 ```bash
 
 ```
 
-
 ## Integrate with Puppeteer
 
 > [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.
 
-Write and save the following code as `./demo.ts`.
+### Step 1. install dependencies
 
-```typescript
-import puppeteer, { Viewport } from 'puppeteer';
-import { PuppeteerAgent } from '@midscene/web/puppeteer';
-
-// init Puppeteer page
-const browser = await puppeteer.launch({
-  headless: false, // here we use headed mode to help debug
-});
-
-const page = await browser.newPage();
-await page.goto('https://www.ebay.com');
-await page.waitForNavigation({
-  timeout: 20 * 1000,
-  waitUntil: 'networkidle0',
-});
-const page = await launchPage();
+```bash
+npm install @midscene/web --save-dev
+npm install puppeteer ts-node --save-dev 
+```
 
-// 👀 init MidScene agent 
-const mid = new PuppeteerAgent(page);
+### Step 2. write scripts
 
-// 👀 perform a search
-await mid.aiAction('type "Headphones" in search box, hit Enter');
-await sleep(5000);
+Write and save the following code as `./demo.ts`.
 
-// 👀 find the items
-const items = await mid.aiQuery(
-  '{itemTitle: string, price: Number}[], find item in list and corresponding price',
+```typescript
+import puppeteer from "puppeteer";
+import { PuppeteerAgent } from "@midscene/web";
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+Promise.resolve(
+  (async () => {
+    const browser = await puppeteer.launch({
+      headless: false, // here we use headed mode to help debug
+    });
+
+    const page = await browser.newPage();
+    await page.setViewport({
+      width: 1280,
+      height: 800,
+      deviceScaleFactor: 1,
+    });
+
+    await page.goto("https://www.ebay.com");
+    await sleep(5000);
+
+    // 👀 init MidScene agent
+    const mid = new PuppeteerAgent(page);
+
+    // 👀 type keywords, perform a search
+    await mid.aiAction('type "Headphones" in search box, hit Enter');
+    await sleep(5000);
+
+    // 👀 understand the page content, find the items
+    const items = await mid.aiQuery(
+      "{itemTitle: string, price: Number}[], find item in list and corresponding price"
+    );
+    console.log("headphones in stock", items);
+
+    await browser.close();
+  })()
 );
-console.log('headphones in stock', items);
 ```
 
 :::tip
@@ -116,6 +163,8 @@ await mid.aiQuery(
 ```
 :::
 
+### Step 3. run
+
 Using ts-node to run, you will get the data of Headphones on ebay:
 
 ```bash
@@ -135,6 +184,13 @@ npx ts-node demo.ts
 # ]
 ```
 
-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.
+### Step 4. view test report after running
+
+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.
+
+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.
+
+
+## Demo Projects
 
-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.
+You can clone a complete demo project in this repo: https://github.com/web-infra-dev/midscene-example/
diff --git a/apps/site/docs/en/index.md b/apps/site/docs/en/index.md
@@ -24,7 +24,7 @@ features:
     icon: 🤔
   - title: Intuitive Assertion
     details: Make assertions in natural language. It’s all based on AI understanding.
-    icon: 🤔
+    icon: ⛳
   - title: Out-of-box LLM
     details: It is fine to use public multimodal LLMs like GPT-4o. There is no need for any custom training.
     icon: 🪓

diff --git a/apps/site/docs/zh/docs/getting-started/quick-start.md b/apps/site/docs/zh/docs/getting-started/quick-start.md
@@ -6,25 +6,27 @@
 
 > [Puppeteer](https://pptr.dev/) 是一个 Node.js 库，它通过 DevTools Protocol 或 WebDriver BiDi 提供了用于控制 Chrome 或 Firefox 的高级 API。默认情况下，Puppeteer 运行在无头模式（headless mode, 即没有可见的 UI），但也可以配置为在有头模式（headed mode, 即有可见的浏览器界面）下运行。
 
+## 准备工作
+
 配置 API Key
 
 ```bash
 # replace by your own
 export OPENAI_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"
 ```
 
-安装依赖 
+## 集成到 Playwright
+
+> [Playwright.js](https://playwright.com/) 是由微软开发的一个开源自动化库，主要用于对网络应用程序进行端到端测试（end-to-end test）和网页抓取。
+
+这里我们假设你已经拥有一个集成了 Playwright 的仓库。
+
+### 新增依赖 
 
 ```bash
 npm install @midscene/web --save-dev
-# 供 demo 使用
-npm install puppeteer ts-node --save-dev 
 ```
 
-## 集成到 Playwright
-
-> [Playwright.js](https://playwright.com/) 是由微软开发的一个开源自动化库，主要用于对网络应用程序进行端到端测试（end-to-end test）和网页抓取。
-
 ### 第一步：更新 playwright.config.ts
 
 ```diff
@@ -47,57 +49,119 @@ import { PlaywrightAiFixture } from '@midscene/web';
 export const test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture());
 ```
 
-TODO__________________________
+### 第三步：编写测试用例
 
-## 集成到 Puppeteer
-
-> [Puppeteer](https://pptr.dev/) 是一个 Node.js 库，它通过 DevTools 协议或 WebDriver BiDi 提供控制 Chrome 或 Firefox 的高级 API。Puppeteer 默认在无界面模式（headless）下运行，但可以配置为在可见的浏览器模式（headed）中运行。
-
-编写下方代码，保存为 `./demo.ts`
+编写下方代码，保存为 `./e2e/ebay-search.spec.ts`
 
 ```typescript
-import puppeteer, { Viewport } from 'puppeteer';
-import { PuppeteerAgent } from '@midscene/web/puppeteer';
+import { expect } from "@playwright/test";
+import { test } from "./fixture";
 
-// 初始化 Puppeteer Page
-const browser = await puppeteer.launch({
-  headless: false, // here we use headed mode to help debug
+test.beforeEach(async ({ page }) => {
+  page.setViewportSize({ width: 400, height: 905 });
+  await page.goto("https://www.ebay.com");
+  await page.waitForLoadState("networkidle");
 });
 
-const page = await browser.newPage();
-await page.goto('https://www.ebay.com');
-await page.waitForNavigation({
-  timeout: 20 * 1000,
-  waitUntil: 'networkidle0',
+test("search headphone on ebay", async ({ ai, aiQuery }) => {
+  // 👀 输入关键字，执行搜索
+  // 注：尽管这是一个英文页面，你也可以用中文指令控制它
+  await ai('在搜索框输入 "Headphones" ，敲回车');
+
+  // 👀 找到列表里耳机相关的信息
+  const items = await aiQuery(
+    '{itemTitle: string, price: Number}[], 找到列表里的商品标题和价格'
+  );
+
+  console.log("headphones in stock", items);
+  expect(items?.length).toBeGreaterThan(0);
 });
-const page = await launchPage();
 
-// 👀 初始化 MidScene agent 
-const mid = new PuppeteerAgent(page);
+```
+
+### Step 4. 运行测试用例
+
+```bash
+npx playwright test ./e2e/ebay-search.spec.ts
+```
+
+### Step 5. 查看测试报告
+
+Follow the instructions in the command line to server the report
+
+```bash
+
+```
+
+## 集成到 Puppeteer
+
+> [Puppeteer](https://pptr.dev/) 是一个 Node.js 库，它通过 DevTools 协议或 WebDriver BiDi 提供控制 Chrome 或 Firefox 的高级 API。Puppeteer 默认在无界面模式（headless）下运行，但可以配置为在可见的浏览器模式（headed）中运行。
 
-// 👀 执行搜索
-await mid.aiAction('type "Headphones" in search box, hit Enter');
-await sleep(5000);
+### 第一步：安装依赖
 
-// 👀 提取数据
-const items = await mid.aiQuery(
-  '{itemTitle: string, price: Number}[], find item in list and corresponding price',
+```bash
+npm install @midscene/web --save-dev
+npm install puppeteer ts-node --save-dev 
+```
+
+### 第二步：编写脚本
+
+编写下方代码，保存为 `./demo.ts`
+
+```typescript
+import puppeteer from "puppeteer";
+import { PuppeteerAgent } from "@midscene/web";
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+Promise.resolve(
+  (async () => {
+    const browser = await puppeteer.launch({
+      headless: false, // here we use headed mode to help debug
+    });
+
+    const page = await browser.newPage();
+    await page.setViewport({
+      width: 1280,
+      height: 800,
+      deviceScaleFactor: 1,
+    });
+
+    await page.goto("https://www.ebay.com");
+    await sleep(5000);
+
+    // 👀 初始化 MidScene agent 
+    const mid = new PuppeteerAgent(page);
+
+    // 👀 执行搜索
+    // 注：尽管这是一个英文页面，你也可以用中文指令控制它
+    await mid.aiAction('在搜索框输入 "Headphones" ，敲回车');
+    await sleep(5000);
+
+    // 👀 理解页面，提取数据
+    const items = await mid.aiQuery(
+      '{itemTitle: string, price: Number}[], 找到列表里的商品标题和价格',
+    );
+    console.log("耳机商品信息", items);
+
+    await browser.close();
+  })()
 );
-console.log('headphones in stock', items);
 ```
 
 :::tip
 
 你可能已经注意到了，上述文件中的关键代码只有两行，且都是用自然语言编写的
 
 ```typescript
-await mid.aiAction('type "Headphones" in search box, hit Enter');
+await mid.aiAction('在搜索框输入 "Headphones" ，敲回车');
 await mid.aiQuery(
-  '{itemTitle: string, price: Number}[], find item in list and corresponding price',
+  '{itemTitle: string, price: Number}[], 找到列表里的商品标题和价格',
 );
 ```
 :::
 
+### 第三步：运行
+
 使用 `ts-node` 来运行，你会看到命令行打印出了耳机的商品信息：
 
 ```bash
@@ -117,6 +181,12 @@ npx ts-node demo.ts
 # ]
 ```
 
-运行 MidScene 之后，系统会生成一个日志文件，默认存放在 `./midscene_run/latest.web-dump.json`。然后，你可以把这个文件导入 [可视化工具](/visualization/)，这样你就能更清楚地了解整个过程。
+### 第四步：查看运行报告
+
+运行 MidScene 之后，系统会生成一个日志文件，默认存放在 `./midscene_run/report/latest.web-dump.json`。然后，你可以把这个文件导入 [可视化工具](/visualization/)，这样你就能更清楚地了解整个过程。
+
+在 [可视化工具](/visualization/) 中，点击 `Load Demo` 按钮，你将能够看到上方代码的运行结果以及其他的一些示例。
+
+## 完整的样例工程
 
-在 [可视化工具](/visualization/) 中，点击 `Load Demo` 按钮，你将能够看到上方代码的运行结果以及其他的一些示例。
+你可以在这里 Clone 完整的样例工程项目： https://github.com/web-infra-dev/midscene-example/