告别Python版！手把手教你用Node.js 18和pnpm搞定Playwright测试环境（MacOS保姆级教程）-编程实验室

告别Python版！手把手教你用Node.js 18和pnpm搞定Playwright测试环境（MacOS保姆级教程）

如果你是一名前端或Node.js开发者，厌倦了全网铺天盖地的Python版Playwright教程，那么这篇文章正是为你准备的。我们将带你从零开始，在MacOS上搭建一个基于Node.js 18和pnpm的Playwright测试环境，让你彻底摆脱Python的束缚，享受JavaScript生态的流畅体验。

Playwright作为微软推出的现代化端到端测试框架，支持Chromium、WebKit和Firefox三大渲染引擎，无论是本地开发还是CI环境都能游刃有余。与Python版本相比，Node.js版本在前端项目中的集成更加无缝，调试体验也更符合前端开发者的习惯。

1. 环境准备：从Homebrew到Node.js 18

在开始之前，确保你的MacOS系统版本在12 Monterey或13 Ventura以上。我们将使用Homebrew作为基础包管理工具，它不仅安装简单，还能帮助我们轻松管理各种开发依赖。

首先打开终端，执行以下命令安装Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，将Homebrew添加到你的PATH环境变量中：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc source ~/.zshrc

接下来，我们将安装Node.js 18 LTS版本，这是目前Playwright官方推荐的最稳定版本：

brew install node@18

安装完成后，验证Node.js和npm的版本：

node -v # 应该显示v18.x.x npm -v # 应该显示9.x.x

提示：如果你之前安装过其他版本的Node.js，建议使用nvm来管理多版本，避免冲突。

2. pnpm：更快的包管理方案

npm虽然是Node.js的默认包管理器，但在大型项目中性能表现不佳。pnpm作为替代方案，不仅安装速度更快，还能显著减少磁盘空间占用。让我们来安装pnpm：

brew install pnpm

为了加速国内下载速度，我们将pnpm的registry切换为阿里云镜像：

pnpm config set registry https://registry.npmmirror.com

验证pnpm安装是否成功：

pnpm -v # 应该显示8.x.x

pnpm相比npm/yarn有几个显著优势：

磁盘空间节省：所有依赖只保存一份在全局store中
安装速度快：并行下载和硬链接机制大幅提升效率
严格模式：避免幽灵依赖问题，项目更健壮

3. Playwright核心安装与配置

现在来到重头戏——安装Playwright。我们将创建一个专门的项目目录来管理测试代码：

mkdir playwright-demo && cd playwright-demo pnpm init -y

接着安装Playwright及相关测试依赖：

pnpm create playwright

这个命令会完成以下几件事：

创建基本的测试目录结构
安装@playwright/test包
下载Chromium、WebKit和Firefox浏览器二进制文件

注意：浏览器下载可能会比较耗时，特别是在网络状况不佳的情况下。如果遇到下载失败，可以尝试设置环境变量来使用国内镜像：

export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright pnpm exec playwright install

安装完成后，验证Playwright是否正常工作：

pnpm exec playwright --version

你应该能看到类似Version 1.40.0的输出，表示安装成功。

4. IDE配置与开发体验优化

虽然任何文本编辑器都可以编写Playwright测试，但VSCode提供了最佳的开发体验，特别是微软官方提供的Playwright插件。让我们来配置一个高效的开发环境：

首先下载并安装VSCode，然后安装以下扩展：

Playwright Test for VSCode：官方测试运行器支持
ESLint：JavaScript代码质量检查
Prettier：代码自动格式化

在项目根目录下创建.vscode/settings.json文件，添加以下配置：

{ "playwright.env": { "PWDEBUG": "console" }, "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.formatOnSave": true, "typescript.tsdk": "node_modules/typescript/lib" }

现在你可以通过以下命令在VSCode中打开项目：

code .

VSCode的Playwright插件提供了诸多强大功能：

测试用例的图形化运行界面
实时调试支持
测试结果可视化
代码自动补全

5. 实战：编写并运行第一个测试

让我们创建一个简单的测试用例，验证我们的环境是否配置正确。在tests目录下创建example.spec.ts文件：

import { test, expect } from '@playwright/test'; test('basic test', async ({ page }) => { await page.goto('https://playwright.dev/'); const title = page.locator('.navbar__title'); await expect(title).toHaveText('Playwright'); });

这个测试用例会：

打开Playwright官网
定位导航栏标题元素
验证标题文本是否为"Playwright"

你可以通过以下命令运行测试：

pnpm exec playwright test

如果想在浏览器中看到测试过程（而不是默认的无头模式），可以添加--headed参数：

pnpm exec playwright test --headed

测试完成后，生成HTML报告查看详细结果：

pnpm exec playwright show-report

6. 高级配置与性能优化

为了让Playwright更好地适应你的项目需求，这里分享几个实用的配置技巧。

6.1 并行测试执行

Playwright默认会并行运行测试以加快执行速度。你可以通过workers选项控制并行度：

// playwright.config.ts import { defineConfig } from '@playwright/test'; export default defineConfig({ workers: process.env.CI ? 2 : 4, });

6.2 浏览器配置

在playwright.config.ts中，你可以定义多种浏览器配置：

import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, }, { name: 'webkit', use: { ...devices['Desktop Safari'] }, }, ], });

6.3 网络模拟

Playwright可以模拟不同的网络条件，测试网站在慢速网络下的表现：

test('slow network test', async ({ page }) => { await page.goto('https://your-site.com'); await page.emulateNetworkConditions({ download: 500 * 1024 / 8, // 500kb/s upload: 500 * 1024 / 8, latency: 100 }); // 你的测试代码 });

7. 常见问题排查

即使按照教程一步步操作，你可能还是会遇到一些问题。以下是几个常见问题及解决方案：

问题1：浏览器下载失败

Error: Failed to download Chromium, exceeded max retry attempts

解决方案：

export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright pnpm exec playwright install

问题2：测试超时

默认测试超时时间是30秒，如果需要更长可以这样设置：

test('slow test', async ({ page }) => { test.setTimeout(120000); // 2分钟 // 你的测试代码 });

问题3：元素定位失败

确保你的选择器足够稳定，避免使用可能变化的类名或ID。Playwright提供了多种定位策略：

// 通过文本内容定位 page.locator('text=Submit'); // 通过CSS选择器定位 page.locator('#submit-button'); // 通过XPath定位 page.locator('//button[@id="submit"]'); // 通过ARIA属性定位 page.locator('[aria-label="Submit"]');

在实际项目中，我发现结合page.getByRole()和page.getByText()通常能提供最稳定的定位方式。