shortest

英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

最短

由 AI 驱动的自然语言端到端测试框架。

功能

• 自然语言 E2E 测试框架
• 使用 Anthropic Claude API 的 AI 驱动测试执行
• 基于 Playwright 构建
• 支持 2FA 的 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("Login to the app using email and password", {
  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("Login to the app using username and password", {
  username: process.env.USERNAME,
  password: process.env.PASSWORD,
}).after(async ({ page }) => {
  // Get current user's clerk ID from the page
  const clerkId = await page.evaluate(() => {
    return window.localStorage.getItem("clerk-user");
  });

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

  // Query the database
  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 });
});

链式测试

最短支持灵活的测试链模式：

// Sequential test chain
shortest([
  "user can login with email and password",
  "user can modify their account-level refund policy",
]);

// Reusable test flows
const loginAsLawyer = "login as lawyer with valid credentials";
const loginAsContractor = "login as contractor with valid credentials";
const allAppActions = ["send invoice to company", "view invoices"];

// Combine flows with spread operator
shortest([loginAsLawyer, ...allAppActions]);
shortest([loginAsContractor, ...allAppActions]);

API 测试

使用自然语言测试 API 端点

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

shortest(
  "Ensure the response contains only active users",
  req.fetch({
    url: "/users",
    method: "GET",
    params: new URLSearchParams({
      active: true,
    }),
  }),
);

或者简单地说：

shortest(`
  Test the API GET endpoint ${API_BASE_URI}/users with query parameter { "active": true }
  Expect the response to contain only active users
`);

运行测试

pnpm shortest                   # Run all tests
pnpm shortest login.test.ts     # Run specific tests from a file
pnpm shortest login.test.ts:23  # Run specific test from a file using a line number
pnpm shortest --headless        # Run in headless mode using

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

CI设置

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

在这里查看示例

GitHub 2FA 登录设置

最短支持使用GitHub双重认证登录。用于GitHub认证测试：

1. 进入你的仓库设置
2. 进入“密码与认证”
3. 点击“认证器应用”
4. 选择“使用你的身份验证器应用”
5. 点击“设置密钥”以获取OTP密钥
6. 将 OTP 密钥添加到你的 .env.local 文件中，或使用 Shortest CLI 添加它
7. 将终端显示的2FA代码输入Github的Authenticator设置页面，完成流程

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

环境设置

在 .env.local 中需要:

ANTHROPIC_API_KEY=your_api_key
GITHUB_TOTP_SECRET=your_secret  # Only for GitHub auth tests

最短 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

环境设置

针对反工作团队成员

拉取 Vercel 环境变量：

pnpm i -g vercel
vercel link
vercel env pull

设置数据库

pnpm drizzle-kit generate
pnpm db:migrate
pnpm db:seed # creates stripe products, currently unused

服务配置

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

本地运行

运行开发服务器：

pnpm dev

在你的浏览器中打开 http://localhost:3000 来查看应用的运行情况。