Shortest

基于 AI 的自然语言端到端测试框架。

特性

• 自然语言端到端测试框架
• 使用 Anthropic Claude API 进行 AI 驱动的测试执行
• 基于 Playwright 构建
• 支持双因素认证的 GitHub 集成
• 使用 Mailosaur 进行邮件验证

在您的项目中使用 Shortest

如果对您有帮助，这里有一段简短的视频！

安装

使用 shortest init 命令可以在新项目或现有项目中简化设置流程。

shortest init 命令会：

npx @antiwork/shortest init

这将：

• 如果尚未安装，自动将 @antiwork/shortest 包作为开发依赖项安装
• 创建一个包含样板配置的默认 shortest.config.ts 文件
• 生成一个 .env.local 文件（如果不存在），其中包含所需环境变量的占位符，例如 ANTHROPIC_API_KEY
• 将 .env.local 和 .shortest/ 添加到 .gitignore

快速入门

1. 确定您的测试入口，并在配置文件 shortest.config.ts 中添加您的 Anthropic API 密钥。

import type { ShortestConfig } from "@antiwork/shortest";

export default {
  headless: false,
  baseUrl: "http://localhost:3000",
  browser: {
    contextOptions: {
      ignoreHTTPSErrors: true
    },
  },
  testPattern: "**/*.test.ts",
  ai: {
    provider: "anthropic",
  },
} satisfies ShortestConfig;

Anthropic API 密钥默认为 SHORTEST_ANTHROPIC_API_KEY 或 ANTHROPIC_API_KEY 环境变量。可以通过 ai.config.apiKey 覆盖。

可选地，您还可以在配置文件中使用 browser.contextOptions 属性来配置浏览器行为。这允许您传递自定义的 Playwright 浏览器上下文选项。

2. 使用配置中指定的模式创建测试文件：app/login.test.ts

import { shortest } from "@antiwork/shortest";

shortest("使用邮箱和密码登录应用", {
  username: process.env.GITHUB_USERNAME,
  password: process.env.GITHUB_PASSWORD,
});

使用回调函数

您也可以使用回调函数来添加额外的断言和其他逻辑。AI 会在浏览器中的测试执行完成后执行该回调函数。

import { shortest } from "@antiwork/shortest";
import { db } from "@/lib/db/drizzle";
import { users } from "@/lib/db/schema";
import { eq } from "drizzle-orm";

shortest("使用用户名和密码登录应用", {
  username: process.env.USERNAME,
  password: process.env.PASSWORD,
}).after(async ({ page }) => {
  // 从页面获取当前用户的 Clerk ID
  const clerkId = await page.evaluate(() => {
    return window.localStorage.getItem("clerk-user");
  });

  if (!clerkId) {
    throw new Error("数据库中未找到用户");
  }

  // 查询数据库
  const [user] = await db
    .select()
    .from(users)
    .where(eq(users.clerkId, clerkId))
    .limit(1);

  expect(user).toBeDefined();
});

生命周期钩子

您可以使用生命周期钩子在测试前后运行代码。

import { shortest } from "@antiwork/shortest";

shortest.beforeAll(async ({ page }) => {
  await clerkSetup({
    frontendApiUrl:
      process.env.PLAYWRIGHT_TEST_BASE_URL ?? "http://localhost:3000",
  });
});

shortest.beforeEach(async ({ page }) => {
  await clerk.signIn({
    page,
    signInParams: {
      strategy: "email_code",
      identifier: "iffy+clerk_test@example.com",
    },
  });
});

shortest.afterEach(async ({ page }) => {
  await page.close();
});

shortest.afterAll(async ({ page }) => {
  await clerk.signOut({ page });
});

测试链式调用

Shortest 支持灵活的测试链式调用模式：

// 顺序测试链
shortest([
  "用户可以使用邮箱和密码登录",
  "用户可以修改其账户级别的退款政策",
]);

// 可复用的测试流程
const loginAsLawyer = "使用有效凭证登录律师账号";
const loginAsContractor = "使用有效凭证登录承包商账号";
const allAppActions = ["向公司发送发票", "查看发票"];

// 使用展开运算符组合流程
shortest([loginAsLawyer, ...allAppActions]);
shortest([loginAsContractor, ...allAppActions]);

API 测试

使用自然语言测试 API 端点

const req = new APIRequest({
  baseURL: API_BASE_URI,
});

shortest(
  "确保响应仅包含活跃用户",
  req.fetch({
    url: "/users",
    method: "GET",
    params: new URLSearchParams({
      active: true,
    }),
  }),
);

或者更简单地：

shortest(`
  测试 API GET 端点 ${API_BASE_URI}/users，查询参数为 { "active": true }
  预期响应应仅包含活跃用户
`);

运行测试

pnpm shortest                   # 运行所有测试
pnpm shortest login.test.ts     # 运行文件中的特定测试
pnpm shortest login.test.ts:23  # 使用行号运行文件中的特定测试
pnpm shortest --headless        # 以无头模式运行

您可以在 examples 目录中找到示例测试。

CI 设置

您可以通过在无头模式下运行测试，在 CI/CD 流水线中运行 Shortest。请确保将您的 Anthropic API 密钥添加到 CI/CD 流水线的密钥中。

在此处查看示例

GitHub 2FA 登录设置

Shortest 支持使用 GitHub 2FA 登录。对于 GitHub 身份验证测试：

1. 前往您的仓库设置
2. 导航到“密码和身份验证”
3. 单击“身份验证器应用”
4. 选择“使用身份验证器应用”
5. 单击“设置密钥”以获取 OTP 密钥
6. 将 OTP 密钥添加到您的 .env.local 文件中，或使用 Shortest CLI 添加
7. 将终端中显示的 2FA 代码输入到 GitHub 的身份验证器设置页面中，以完成设置过程

shortest --github-code --secret=<OTP_SECRET>

环境设置

.env.local 中需要以下内容：

ANTHROPIC_API_KEY=your_api_key
GITHUB_TOTP_SECRET=your_secret  # 仅用于 GitHub 身份验证测试

Shortest CLI 开发

NPM 包位于 packages/shortest/。请参阅 CONTRIBUTING 指南。

Web 应用开发

本指南将帮助您为本地开发设置 Shortest Web 应用程序。

前置条件

• React >=19.0.0（若与 Next.js 14+ 或 Server Actions 搭配使用）
• Next.js >=14.0.0（若使用 Server Components/Actions）

[!警告] 在 Next.js 14+ 项目中将此包与 React 18 一起使用，可能会导致与 Server Actions 和 useFormStatus 的类型冲突。

如果遇到表单操作或 React 钩子相关的类型错误，请确保使用 React 19。

开始使用

1. 克隆仓库：

git clone https://github.com/antiwork/shortest.git
cd shortest

2. 安装依赖：

npm install -g pnpm
pnpm install

环境设置

对于 Antiwork 团队成员

拉取 Vercel 环境变量：

pnpm i -g vercel
vercel link
vercel env pull

对于其他贡献者

1. 运行 pnpm run setup 来配置环境变量。
2. 设置向导会提示您输入相关信息。更多详情请参阅下方的“服务配置”部分。

设置数据库

pnpm drizzle-kit generate
pnpm db:migrate
pnpm db:seed # 创建 Stripe 产品，目前未使用

服务配置

您需要为本地开发设置以下服务。如果您不是 Antiwork Vercel 团队成员，则需要运行设置向导 pnpm run setup，或者手动配置这些服务，并将相应的环境变量添加到您的 .env.local 文件中：

Clerk

1. 访问 clerk.com，创建一个新的应用。
2. 为应用命名，然后仅保留 GitHub 登录方式，禁用其他所有登录方法。
3. 创建完成后，将环境变量复制到您的 .env.local 文件中。
4. 在 Clerk 控制台中，关闭“要求使用同一设备和浏览器”的设置，以确保与 Mailosaur 的测试能够正常工作。

Vercel Postgres

1. 登录 vercel.com 的仪表板。
2. 转到“存储”选项卡，点击“创建数据库”按钮。
3. 在“浏览存储”菜单中选择 Postgres。
4. 从“快速入门”的 .env.local 选项卡中复制您的环境变量。

Anthropic

1. 登录 anthropic.com 的仪表板，获取您的 API 密钥。
   • 注意：如果您之前从未进行过此操作，可能需要回答一些问题，并为账户充值。测试应用程序并不需要太多资金。

Stripe

1. 登录 stripe.com 的“开发者”仪表板。
2. 打开“测试模式”。
3. 转到“API 密钥”选项卡，复制您的“密钥”。
4. 打开项目的终端，输入 pnpm run stripe:webhooks。系统会提示您使用验证码登录，随后生成您的 STRIPE_WEBHOOK_SECRET。

GitHub OAuth

1. 创建 GitHub OAuth 应用程序：

   • 前往您的 GitHub 账户设置。
   • 导航至“开发者设置” > “OAuth 应用程序” > “新建 OAuth 应用程序”。
   • 填写应用详细信息：
     • 应用名称：任意选择一个名称
     • 主页 URL：设置为 http://localhost:3000，用于本地开发
     • 授权回调 URL：使用 Clerk 提供的回调 URL（见下图）

2. 在 Clerk 中配置 GitHub OAuth：

   • 前往您的 Clerk 控制台。
   • 导航至“配置” > “SSO 连接” > “GitHub”。
   • 选择“使用自定义凭据”。
   • 输入您刚刚创建的 GitHub OAuth 应用程序中的“客户端 ID”和“客户端密钥”。
   • 添加 repo 到“作用域”中。

Mailosaur

1. 在 mailosaur.com 注册一个 Mailosaur 账户。
2. 创建一个新的收件箱/服务器。
3. 转到“API 密钥”页面，创建一个标准密钥。
4. 更新环境变量：
   • MAILOSAUR_API_KEY：您的 API 密钥
   • MAILOSAUR_SERVER_ID：您的服务器 ID

用于测试登录流程的电子邮件格式为 shortest@<MAILOSAUR_SERVER_ID>.mailosaur.net，其中 <MAILOSAUR_SERVER_ID> 是您的服务器 ID。请务必将该邮箱作为新用户添加到 Clerk 应用中。

本地运行

启动开发服务器：

pnpm dev

在浏览器中打开 http://localhost:3000，即可查看应用运行效果。

Shortest 快速上手指南

Shortest 是一个基于 AI 的自然语言端到端（E2E）测试框架。它利用 Anthropic Claude API 理解自然语言指令，并基于 Playwright 执行浏览器自动化测试，支持 GitHub 2FA 登录和 Mailosaur 邮件验证。

环境准备

• Node.js：建议最新 LTS 版本。
• 包管理器：推荐使用 pnpm 或 npm。
• API Key：你需要一个 Anthropic API Key (ANTHROPIC_API_KEY)。
• 前置知识：了解基本的 TypeScript 和 Playwright 概念会有所帮助。

注意：如果你计划在 Next.js 14+ 项目中使用 Server Actions，请确保使用 React >=19.0.0 以避免类型冲突。

安装步骤

在现有或新建的项目根目录下，运行以下初始化命令。该命令会自动安装依赖、生成配置文件和环境变量模板。

npx @antiwork/shortest init

执行后，项目将发生以下变化：

1. 安装 @antiwork/shortest 为开发依赖。
2. 创建默认配置文件 shortest.config.ts。
3. 生成 .env.local 文件（若不存在），其中包含 ANTHROPIC_API_KEY 等变量的占位符。
4. 自动将 .env.local 和 .shortest/ 添加到 .gitignore。

配置环境变量： 编辑 .env.local 文件，填入你的 Anthropic API Key：

ANTHROPIC_API_KEY=your_api_key

基本使用

1. 配置测试入口

编辑 shortest.config.ts，设置基础 URL 和测试文件匹配模式：

import type { ShortestConfig } from "@antiwork/shortest";

export default {
  headless: false, // 设置为 true 可在无头模式下运行
  baseUrl: "http://localhost:3000",
  browser: {
    contextOptions: {
      ignoreHTTPSErrors: true
    },
  },
  testPattern: "**/*.test.ts",
  ai: {
    provider: "anthropic",
  },
} satisfies ShortestConfig;

2. 编写测试用例

Shortest 允许你使用自然语言描述测试步骤。创建测试文件（如 app/login.test.ts）：

import { shortest } from "@antiwork/shortest";

shortest("Login to the app using email and password", {
  username: process.env.GITHUB_USERNAME,
  password: process.env.GITHUB_PASSWORD,
});

AI 会自动解析该描述，并在浏览器中执行相应的登录操作。

3. 运行测试

使用以下命令运行测试：

# 运行所有测试
pnpm shortest

# 运行指定文件的测试
pnpm shortest login.test.ts

# 无头模式运行（适用于 CI/CD）
pnpm shortest --headless

高级用法：添加断言与回调

如果需要更严格的验证，可以使用 .after() 回调函数。AI 执行完浏览器操作后，会运行此回调：

import { shortest } from "@antiwork/shortest";
import { db } from "@/lib/db/drizzle";
import { users } from "@/lib/db/schema";
import { eq } from "drizzle-orm";

shortest("Login to the app using username and password", {
  username: process.env.USERNAME,
  password: process.env.PASSWORD,
}).after(async ({ page }) => {
  // 获取页面中的用户 ID
  const clerkId = await page.evaluate(() => {
    return window.localStorage.getItem("clerk-user");
  });

  if (!clerkId) {
    throw new Error("User not found in database");
  }

  // 数据库断言
  const [user] = await db
    .select()
    .from(users)
    .where(eq(users.clerkId, clerkId))
    .limit(1);

  expect(user).toBeDefined();
});