Setting up Playwright with Next.js

Playwright 是一个测试框架，允许你使用单一 API 来自动化 Chromium、Firefox 和 WebKit。你可以用它来编写端到端 (E2E) 测试。本指南将向你展示如何在 Next.js 中设置 Playwright 并编写你的第一个测试。

快速开始

最快的入门方式是使用 create-next-app 和 with-playwright 示例。这将创建一个已配置好 Playwright 的 Next.js 项目。

Terminal

npx create-next-app@latest --example with-playwright with-playwright-app

手动设置

要安装 Playwright，运行以下命令：

Terminal

npm init playwright
# 或
yarn create playwright
# 或
pnpm create playwright

这将引导你完成一系列提示来为你的项目设置和配置 Playwright，包括添加一个 playwright.config.ts 文件。请参阅 Playwright 安装指南获取逐步指导。

创建你的第一个 Playwright E2E 测试

创建两个新的 Next.js 页面：

pages/index.ts

import Link from "next/link";
 
export default function Home() {
  return (
    <div>
      <h1>首页</h1>
      <Link href="/about">关于</Link>
    </div>
  );
}

pages/about.ts

import Link from "next/link";
 
export default function About() {
  return (
    <div>
      <h1>关于</h1>
      <Link href="/">首页</Link>
    </div>
  );
}

然后，添加一个测试来验证你的导航是否正常工作：

tests/example.spec.ts

import { test, expect } from "@playwright/test";
 
test("应该导航到关于页面", async ({ page }) => {
  // 从索引页面开始 (baseURL 通过 playwright.config.ts 中的 webServer 设置)
  await page.goto("http://localhost:3000/");
  // 找到包含文本 "关于" 的元素并点击它
  await page.click("text=关于");
  // 新的 URL 应该是 "/about" (这里使用了 baseURL)
  await expect(page).toHaveURL("http://localhost:3000/about");
  // 新页面应该包含一个内容为 "关于" 的 h1
  await expect(page.locator("h1")).toContainText("关于");
});

值得注意的是：

如果你在 playwright.config.ts 配置文件中添加了 "baseURL": "http://localhost:3000"，你可以使用 page.goto("/") 而不是 page.goto("http://localhost:3000/")。

运行你的 Playwright 测试

Playwright 将使用三种浏览器（Chromium、Firefox 和 WebKit）模拟用户浏览你的应用，这需要你的 Next.js 服务器正在运行。我们建议针对你的生产代码运行测试，以更接近地模拟你的应用的实际行为。

运行 npm run build 和 npm run start，然后在另一个终端窗口中运行 npx playwright test 来执行 Playwright 测试。

值得注意的是：或者，你可以使用 webServer 功能让 Playwright 启动开发服务器并等待它完全可用。

在持续集成 (CI) 中运行 Playwright

Playwright 默认会在无头模式下运行你的测试。要安装所有 Playwright 依赖，运行 npx playwright install-deps。

你可以从以下资源了解更多关于 Playwright 和持续集成的信息：