Auto Playwright

使用 AI 运行 Playwright 测试。

设置

1. 安装 auto-playwright 依赖：

npm install auto-playwright -D

2. 本包依赖于与 OpenAI（https://openai.com/）的交互。您必须将 API 密钥导出为环境变量，或将其添加到您的 .env 文件中：

export OPENAI_API_KEY='sk-...'

3. 导入并使用 auto 函数：

import { test, expect } from "@playwright/test";
import { auto } from "auto-playwright";

test("auto Playwright 示例", async ({ page }) => {
  await page.goto("/");

  // `auto` 可以查询数据
  // 在此例中，结果是标题的纯文本内容。
  const headerText = await auto("获取标题文本", { page, test });

  // `auto` 可以执行操作
  // 在此例中，`auto` 会找到搜索框并输入文本。
  await auto(`在搜索框中输入 "${headerText}"`, { page, test });

  // `auto` 可以断言页面状态
  // 在此例中，结果是一个布尔值。
  const searchInputHasHeaderText = await auto(
    `搜索框的内容是否等于 "${headerText}"？`,
    { page, test },
  );

  expect(searchInputHasHeaderText).toBe(true);
});

使用 Azure OpenAI 进行设置

包含 StepOptions 类型，并提供连接 Azure OpenAI 所需的值。

import { test, expect } from "@playwright/test";
import { auto } from "auto-playwright";
import { StepOptions } from "../src/types";

const apiKey = "apikey";
const resource = "azure-resource-name";
const model = "model-deployment-name";

const options: StepOptions = {
  model: model,
  openaiApiKey: apiKey,
  openaiBaseUrl: `https://${resource}.openai.azure.com/openai/deployments/${model}`,
  openaiDefaultQuery: { "api-version": "2023-07-01-preview" },
  openaiDefaultHeaders: { "api-key": apiKey },
};

test("auto Playwright 示例", async ({ page }) => {
  await page.goto("/");

  // `auto` 可以查询数据
  // 在此例中，结果是标题的纯文本内容。
  const headerText = await auto("获取标题文本", { page, test }, options);

  // `auto` 可以执行操作
  // 在此例中，`auto` 会找到搜索框并输入文本。
  await auto(`在搜索框中输入 "${headerText}"`, { page, test }, options);

  // `auto` 可以断言页面状态
  // 在此例中，结果是一个布尔值。
  const searchInputHasHeaderText = await auto(
    `搜索框的内容是否等于 "${headerText}"？`,
    { page, test },
    options,
  );

  expect(searchInputHasHeaderText).toBe(true);
});

使用方法

至少，auto 函数需要一个 纯文本提示 和一个包含 page 和 test 对象（可选）的 参数。

auto("<你的提示>", { page, test });

浏览器自动化

不带 test 参数运行：

import { chromium } from "playwright";
import { auto } from "auto-playwright";

(async () => {
  const browser = await chromium.launch({ headless: true });
  const context = await browser.newContext();
  const page = await context.newPage();
  // 导航到某个网站
  await page.goto("https://www.example.com");

  // `auto` 可以查询数据
  // 在此例中，结果是标题的纯文本内容。
  const res = await auto("获取标题文本", { page });

  // 使用 res.query 获取查询结果。
  console.log(res);
  await page.close();
})();

调试

您可以将 debug 属性作为第三个参数传递给 auto 函数。这将打印提示以及 OpenAI 执行的命令。

await auto("获取标题文本", { page, test }, { debug: true });

您也可以设置环境变量 AUTO_PLAYWRIGHT_DEBUG=true，这将为所有 auto 调用启用调试模式。

export AUTO_PLAYWRIGHT_DEBUG=true

支持的浏览器

Playwright 支持的所有浏览器。

其他选项

您可以作为第三个参数传递其他选项：

const options = {
  // 如果为 true，则会在控制台打印调试信息。
  debug: boolean,
  // OpenAI 模型（https://platform.openai.com/docs/models/overview）
  model: "gpt-4-1106-preview",
  // OpenAI 的 API 密钥
  openaiApiKey: "sk-...",
};

auto("<你的提示>", { page, test }, options);

支持的操作与返回值

根据操作的 类型（由 auto 函数推断），会有不同的行为和返回类型。

操作

操作（例如“点击”）是指模拟用户与页面的交互，比如点击链接。如果操作成功，将返回 undefined；如果失败，则会抛出错误，例如：

try {
  await auto("点击链接", { page, test });
} catch (e) {
  console.error("点击链接失败");
}

查询

查询会以字符串形式返回页面上请求的数据，例如：

const linkText = await auto("获取第一个链接的文本", { page, test });

console.log("链接文本是", linkText);

断言

断言是一个问题，它会返回 true 或 false，例如：

const thereAreThreeLinks = await auto("页面上有 3 个链接吗？", {
  page,
  test,
});

console.log(`"页面上有 3 个链接" 是一个 ${thereAreThreeLinks} 的陈述`);

为什么使用 Auto Playwright？

支持的 Playwright 操作

• locator.blur
• locator.boundingBox
• locator.check
• locator.clear
• locator.click
• locator.count
• locator.fill
• locator.getAttribute
• locator.innerHTML
• locator.innerText
• locator.inputValue
• locator.isChecked
• locator.isEditable
• locator.isEnabled
• locator.isVisible
• locator.pressKey
• locator.selectOption
• locator.textContent
• locator.uncheck
• page.goto
• page.keyboard.press

添加新的操作非常简单：只需更新 src/completeTask.ts 中的 functions。

定价

本库是免费的。然而，使用 OpenAI 会产生费用。有关定价的更多信息，请参阅：https://openai.com/pricing/。

<div class="cYdhWw dKnOgO geGbZz bGoBgk jkEels">
  <div class="kSmiQp fPSBzf bnYmbW dXscgu xJzwH jTWvec gzBMzy">
    <h1 class="fwYeZS fwlORb pdjVK bccLBY fsAQjR fyszFl WNJim fzozfU">
      学习 Playwright
    </h1>
    <h2 class="cakMWc ptfck bBmAxp hSiiri xJzwS gnfYng jTWvec fzozfU">
      使用 Playwright 自动化框架学习端到端测试的资源
    </h2>
    <div
      class="bLTbYS gvHvKe cHEBuD ddgODW jsxhGC kdTEUJ ilCTXp iQHbtH yuxBn ilIXfy gPeiPq ivcdqp isDTsq jyZWmS ivdkBK cERSkX hdAwi ezvbLT jNrAaV jsxhGJ fzozCb"
    ></div>
  </div>
  <div class="cYdhWw dpjphg cqUdSC fasMpP">
    <a
      class="gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group"
      href="/blog"
      ><div class="plfYl bccLBY hSiiri fNBpvX">博客</div>
      <div class="jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu">
        <p>深入了解端到端测试的相关主题。</p>
      </div></a
    ><a
      class="gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group"
      href="/ask"
      ><div class="plfYl bccLBY hSiiri fNBpvX">向 AI 提问</div>
      <div class="jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu">
        <p>向 ChatGPT 提出关于 Playwright 的问题。</p>
      </div></a
    ><a
      class="gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group"
      href="/tools"
      ><div class="plfYl bccLBY hSiiri fNBpvX">开发工具</div>
      <div class="jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu">
        <p>面向 QA 工程师的一体化工具箱。</p>
      </div></a
    ><a
      class="gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group"
      href="/jobs"
      ><div class="plfYl bccLBY hSiiri fNBpvX">QA 职位</div>
      <div class="jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu">
        <p>精心挑选的 QA 和自动化相关机会。</p>
      </div></a
    ><a
      class="gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group"
      href="/questions"
      ><div class="plfYl bccLBY hSiiri fNBpvX">问题</div>
      <div class="jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu">
        <p>向 AI 提问并获得关于 Playwright 的解答。</p>
      </div></a
    ><a
      class="gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group"
      href="/discord-forum"
      ><div class="plfYl bccLBY hSiiri fNBpvX">Discord 论坛</div>
      <div class="jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu">
        <p>关于 Playwright 的 Discord 论坛帖子存档。</p>
      </div></a
    ><a
      class="gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group"
      href="/videos"
      ><div class="plfYl bccLBY hSiiri fNBpvX">视频</div>
      <div class="jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu">
        <p>教程、会议演讲以及发布视频。</p>
      </div></a
    ><a
      class="gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group"
      href="/browser-extension"
      ><div class="plfYl bccLBY hSiiri fNBpvX">浏览器扩展</div>
      <div class="jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu">
        <p>用于生成 Playwright 定位器的图形界面。</p>
      </div></a
    ><a
      class="gacSWM dCgFix conipm knkqUc bddCnd dTKJOB leOtqz hEzNkW fNBBKe jTWvec fIMbrO fzozfU group"
      href="/wiki"
      ><div class="plfYl bccLBY hSiiri fNBpvX">QA 百科</div>
      <div class="jqqjPD fWDXZB pKTba bBmAxp hSiiri evbPEu">
        <p>常见端到端测试术语的定义。</p>
      </div></a
    >
  </div>
  <div
    class="kSmiQp fPSBzf pKTba eTDpsp legDhJ hSiiri hdaZLM jTWvec gzBMzy bGySga fzoybr"
  >
    <p class="dXhlDK leOtqz glpWRZ fNCcFz">
      使用 <kbd class="bWhrAL XAzZz cakMWc bUyOMB bmOrOm fyszFl dTmriP">⌘</kbd> +
      <kbd>k</kbd> + “工具”可快速访问所有工具。
    </p>
  </div>
</div>

实现

HTML 净化

auto 函数使用 sanitize-html 对页面的 HTML 进行净化，然后再将其发送给 OpenAI。这样做是为了降低成本并提高生成文本的质量。

ZeroStep

该项目的灵感来源于 ZeroStep。ZeroStep 提供类似的 API，但通过其专有的后端实现了更为健壮的功能。Auto Playwright 的诞生旨在探索 ZeroStep 的底层技术，并为其软件的开源版本奠定基础。对于生产环境，我建议选择使用 ZeroStep。

以下是 Auto Playwright 和 ZeroStep 的对比：

[^3]: 使用 ZeroStep 专有 API。

[^4]: 使用 部分 Playwright API，但主要依赖 Chrome 开发者工具协议 (CDP)。

MIT 许可证

版权所有 © 2023 Reflect Software Inc

特此授予任何人免费获取本软件及其相关文档文件（以下简称“软件”）副本的权利，允许在不受限制的情况下处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售该软件副本的权利；同时允许向任何获得本软件的人提供服务，但须遵守以下条件：

上述版权声明及本许可声明应包含在所有副本或本软件的重要部分中。

本软件按“原样”提供，不提供任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和非侵权性。在任何情况下，作者或版权所有者均不对因合同、侵权或其他原因引起的任何索赔、损害赔偿或其他责任负责，无论这些责任是基于本软件还是基于对本软件的使用或其他方式而产生的。

Auto Playwright 快速上手指南

Auto Playwright 是一个利用 AI（OpenAI）自动执行 Playwright 测试的工具。它允许开发者使用自然语言描述操作（如“点击登录按钮”或“获取标题文本”），而无需编写繁琐的选择器代码，从而降低测试维护成本并加速测试编写。

环境准备

在开始之前，请确保满足以下要求：

• Node.js: 已安装 Node.js (推荐 v16+) 和 npm。
• Playwright: 项目中已安装 @playwright/test。
• OpenAI API Key: 你需要一个有效的 OpenAI API 密钥。
  • 注意：由于网络原因，国内开发者可能需要配置代理或使用支持 OpenAI 接口的国内大模型服务（需兼容 OpenAI API 格式）。

安装步骤

1. 安装依赖 在项目根目录下运行以下命令安装 auto-playwright 作为开发依赖：

   npm install auto-playwright -D
   

2. 配置 API 密钥 该工具依赖 OpenAI 接口。你需要将 API Key 设置为环境变量，或者添加到项目的 .env 文件中：

   export OPENAI_API_KEY='sk-...'
   

   (Windows PowerShell 用户可使用 $env:OPENAI_API_KEY="sk-...")

基本使用

1. 在 Playwright 测试中使用

这是最推荐的用法，可以直接集成到现有的 Playwright 测试套件中。

创建一个测试文件（例如 example.spec.ts）：

import { test, expect } from "@playwright/test";
import { auto } from "auto-playwright";

test("auto Playwright example", async ({ page }) => {
  await page.goto("/");

  // 查询数据：获取 header 的文本内容
  const headerText = await auto("get the header text", { page, test });

  // 执行动作：在搜索框中输入刚才获取的文本
  await auto(`Type "${headerText}" in the search box`, { page, test });

  // 断言状态：检查搜索框内容是否等于 header 文本
  const searchInputHasHeaderText = await auto(
    `Is the contents of the search box equal to "${headerText}"?`,
    { page, test },
  );

  expect(searchInputHasHeaderText).toBe(true);
});

2. 独立浏览器自动化使用

如果不使用 Playwright Test Runner，也可以直接在脚本中使用：

import { chromium } from "playwright";
import { auto } from "auto-playwright";

(async () => {
  const browser = await chromium.launch({ headless: true });
  const context = await browser.newContext();
  const page = await context.newPage();
  
  await page.goto("https://www.example.com");

  // 执行查询
  const res = await auto("get the header text", { page });

  console.log(res);
  
  await page.close();
  await browser.close();
})();

3. 调试模式

如果需要查看 AI 生成的具体提示词和执行命令，可以开启调试模式：

方法一：代码中开启

await auto("get the header text", { page, test }, { debug: true });

方法二：环境变量开启

export AUTO_PLAYWRIGHT_DEBUG=true

核心概念说明

auto 函数会根据你的自然语言提示自动推断操作类型：

• Action (动作): 如 "click the link"。成功返回 undefined，失败抛出错误。
• Query (查询): 如 "Get the text of the first link"。返回字符串结果。
• Assert (断言): 如 "Are there 3 links on the page?"。返回 true 或 false。