Versions
简体中文

集成到 Puppeteer

Puppeteer 是一个 Node.js 库，它通过 DevTools 协议或 WebDriver BiDi 提供控制 Chrome 或 Firefox 的高级 API。Puppeteer 默认在无界面模式（headless）下运行，但可以配置为在可见的浏览器模式（headed）中运行。

样例项目

你可以在这里看到向 Puppeteer 集成的样例项目：https://github.com/web-infra-dev/midscene-example/blob/main/puppeteer-demo

这里还有一个 Puppeteer 和 Vitest 结合的样例项目：https://github.com/web-infra-dev/midscene-example/tree/main/puppeteer-with-vitest-demo

配置 AI 模型服务

将你的模型配置写入环境变量。更多信息请查看 选择 AI 模型。

# 替换为你的 API Key
export OPENAI_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"

# 可能需要更多配置，如模型名称、接入点等，请参考 《选择 AI 模型》文档
export OPENAI_BASE_URL="..."

第一步：安装依赖

npm
yarn
pnpm
bun
npm install @midscene/web puppeteer tsx --save-dev

第二步：编写脚本

编写下方代码，保存为 ./demo.ts

./demo.ts
import puppeteer from "puppeteer";
import { PuppeteerAgent } from "@midscene/web/puppeteer";

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 agent = new PuppeteerAgent(page);

    // 👀 执行搜索
    // 注：尽管这是一个英文页面，你也可以用中文指令控制它
    await agent.aiAction('在搜索框输入 "Headphones" ，敲回车');
    await sleep(5000);

    // 👀 理解页面，提取数据
    const items = await agent.aiQuery(
      '{itemTitle: string, price: Number}[], 找到列表里的商品标题和价格',
    );
    console.log("耳机商品信息", items);

    // 👀 用 AI 断言
    await agent.aiAssert("界面左侧有类目筛选功能");

    await browser.close();
  })()
);

第三步：运行

使用 tsx 来运行，你会看到命令行打印出了耳机的商品信息：

# run
npx tsx demo.ts

# 命令行应该有如下输出
#  [
#   {
#     itemTitle: 'Beats by Dr. Dre Studio Buds Totally Wireless Noise Cancelling In Ear + OPEN BOX',
#     price: 505.15
#   },
#   {
#     itemTitle: 'Skullcandy Indy Truly Wireless Earbuds-Headphones Green Mint',
#     price: 186.69
#   }
# ]

更多 Agent 的 API 讲解请参考 API 参考。

第四步：查看运行报告

当上面的命令执行成功后，会在控制台输出：Midscene - report file updated: /path/to/report/some_id.html， 通过浏览器打开该文件即可看到报告。

PuppeteerAgent 构造函数的更多选项

限制弹窗在当前页面

如果你想要限制页面在当前 tab 打开（比如点击一个带有 target="_blank" 属性的链接），你可以设置 forceSameTabNavigation 选项为 true：

const mid = new PuppeteerAgent(page, {
  forceSameTabNavigation: true,
});

提供自定义动作

可以使用 customActions 选项，通过 defineAction 来扩展 Agent 的动作空间。传入该选项后，这些动作会追加到内置动作中，Agent 在规划（Planning）时就可以调用它们。

import { getMidsceneLocationSchema, z } from '@midscene/core';
import { defineAction } from '@midscene/core/device';

const ContinuousClick = defineAction({
  name: 'continuousClick',
  description: 'Click the same target repeatedly',
  paramSchema: z.object({
    locate: getMidsceneLocationSchema(),
    count: z
      .number()
      .int()
      .positive()
      .describe('How many times to click'),
  }),
  async call(param) {
    const { locate, count } = param;
    console.log('click target center', locate.center);
    console.log('click count', count);
    // 在这里结合 locate + count 实现自定义点击逻辑
  },
});

const agent = new PuppeteerAgent(page, {
  customActions: [ContinuousClick],
});

await agent.aiAction('点击红色按钮五次');

更多关于自定义动作的细节，请参考 集成到任意界面。

更多