1. 项目概述为什么是 Playwright for .NET如果你是一名 .NET 开发者正在为 Web 自动化测试、爬虫或者 RPA机器人流程自动化项目寻找一个可靠的工具那么 Playwright for .NET 绝对值得你投入时间。我最初接触它是因为厌倦了 Selenium 那令人头疼的浏览器驱动管理和偶发性的不稳定。Playwright 由微软出品专为现代 Web 应用设计它原生支持 Chromium、Firefox 和 WebKit 三大浏览器引擎并且提供了跨平台、跨语言的统一 API。对于 .NET 开发者来说这意味着你可以用熟悉的 C# 语言在 Visual Studio 或 Rider 里编写出强大、稳定且执行速度极快的自动化脚本。简单来说Playwright for .NET 解决了几个核心痛点浏览器兼容性一套脚本跑遍三大内核、执行稳定性内置智能等待告别脆弱的Thread.Sleep、开发体验强大的录制工具和调试能力以及性能支持无头模式和多浏览器上下文并行。无论是为你的 ASP.NET Core 应用做端到端测试还是需要自动化处理一些网页数据它都能成为你得力的“数字员工”。接下来我将从一个 .NET 开发者的实战视角带你从零开始深入掌握 Playwright for .NET 的方方面面。2. 环境准备与项目初始化在开始编写第一行代码之前正确的环境搭建是成功的第一步。这个过程比想象中要简单但有些细节不注意后面可能会踩坑。2.1 安装 .NET SDK 与创建项目首先确保你的开发机上安装了 .NET 6 或更高版本的 SDK。你可以通过命令行dotnet --version来检查。我推荐使用最新的 LTS 版本以获得最好的性能和兼容性。创建一个新的控制台应用项目作为我们的 playground 是最佳起点dotnet new console -n PlaywrightDemo cd PlaywrightDemo2.2 安装 Playwright NuGet 包接下来通过 NuGet 包管理器安装 Playwright。这里有两个关键包Microsoft.Playwright 这是核心库包含了所有的 API。Microsoft.Playwright.NUnit或Microsoft.Playwright.MSTest 如果你计划将 Playwright 用于单元测试框架这是非常常见的用法需要安装对应的测试适配器。这里我们以 NUnit 为例因为它与 Playwright 的集成非常流畅。使用 .NET CLI 安装dotnet add package Microsoft.Playwright dotnet add package Microsoft.Playwright.NUnit注意 安装Microsoft.Playwright包时它会在项目目录下引入一个Drivers文件夹里面包含了 Playwright 的工具脚本。但这并不会自动安装浏览器。浏览器安装是一个独立的步骤。2.3 安装浏览器二进制文件这是 Playwright 设计上非常聪明的一点它将浏览器管理与代码依赖分离。你需要通过 Playwright 提供的 CLI 工具来安装所需的浏览器。这确保了团队中所有成员、CI/CD 流水线使用的浏览器版本完全一致。在项目根目录下执行dotnet tool update --global Microsoft.Playwright.CLI playwright installplaywright install命令会下载 Chromium、Firefox 和 WebKit 的最新兼容版本。如果你只需要其中某一个可以指定例如playwright install chromium。实操心得 在国内网络环境下下载浏览器可能会非常慢甚至失败。这里有两个解决方案使用镜像源 设置环境变量PLAYWRIGHT_DOWNLOAD_HOST。例如在 PowerShell 中临时设置$env:PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright然后再运行playwright install。这是最推荐的方法。手动下载 如果 CLI 安装失败可以去 GitHub Releases 页面手动下载对应平台的浏览器包解压到用户目录下的特定缓存路径如%USERPROFILE%\AppData\Local\ms-playwrighton Windows。不过手动管理版本比较麻烦优先推荐镜像方案。至此你的 .NET 项目已经准备好了所有必要的依赖。接下来让我们编写第一个脚本感受一下 Playwright 的流畅。3. 第一个脚本从录制到理解对于新手最快上手的方式莫过于使用 Playwright 的录制功能。它能将你的浏览器操作直接转换成 C# 代码。3.1 使用 Codegen 录制脚本在项目目录下打开终端运行playwright codegen https://www.bing.com这会自动打开两个窗口一个浏览器窗口和一个 Playwright Inspector 窗口。你在浏览器里的所有操作点击、输入、导航都会被实时转换成代码显示在 Inspector 里并且你可以选择生成 C# 代码。例如你去 Bing 首页在搜索框输入“Playwright .NET”然后点击搜索按钮。Inspector 会生成类似如下的代码// 这是录制生成的代码框架 await page.GotoAsync(https://www.bing.com/); await page.Locator(input[nameq]).ClickAsync(); await page.Locator(input[nameq]).FillAsync(Playwright .NET); await page.Locator(input[nameq]).PressAsync(Enter);录制结束后你可以将这些代码复制到你的Program.cs中。但千万不要止步于此。录制的代码是一个很好的起点但往往不够健壮比如使用了脆弱的 CSS 选择器和结构化。我们的目标是理解并优化它。3.2 编写结构化的第一个脚本让我们抛开录制手动编写一个更健壮、可读性更好的版本。创建一个新的BasicAutomation.cs文件using Microsoft.Playwright; class BasicAutomation { public static async Task Main() { // 1. 创建 Playwright 实例 using var playwright await Playwright.CreateAsync(); // 2. 启动浏览器这里以 Chromium 无头模式为例 await using var browser await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions { Headless false // 设置为 true 则不显示浏览器界面适合 CI/CD }); // 3. 创建浏览器上下文Context和页面Page // Context 相当于一个独立的会话可以隔离 cookies、localStorage 等 var context await browser.NewContextAsync(); var page await context.NewPageAsync(); // 4. 导航到目标页面 await page.GotoAsync(https://www.bing.com); Console.WriteLine($页面标题: {await page.TitleAsync()}); // 5. 定位元素并交互 - 使用更可靠的定位器 // 优先使用 getByRole, getByText, getByPlaceholder 等语义化定位器 var searchBox page.GetByPlaceholder(搜索网页); await searchBox.ClickAsync(); await searchBox.FillAsync(Playwright for .NET); await searchBox.PressAsync(Enter); // 6. 等待导航完成并获取结果 await page.WaitForURLAsync(**/search?qPlaywright.NET**); // 等待搜索结果元素出现 var firstResult page.Locator(#b_results li.b_algo h2 a).First; await firstResult.WaitForAsync(new LocatorWaitForOptions { State WaitForSelectorState.Attached }); Console.WriteLine($第一个结果标题: {await firstResult.TextContentAsync()}); // 7. 可选截图 await page.ScreenshotAsync(new PageScreenshotOptions { Path search_results.png }); Console.WriteLine(自动化任务完成。); // 浏览器和上下文会在 using 块结束时自动关闭 } }关键点解析Playwright.CreateAsync(): 这是所有操作的起点管理着浏览器驱动。LaunchAsync: 启动浏览器进程。Headless: false让你能看到操作过程便于调试。BrowserContext: 这是一个核心概念。每个 Context 是独立的你可以用它来模拟不同的用户会话、设备如手机/平板或设置不同的权限如地理定位、通知。这对于测试多用户场景或需要登录态隔离的情况至关重要。Page: 代表一个标签页。定位器Locator: 这是 Playwright 的精华。page.GetByPlaceholder(...)是推荐的方式它比直接写 CSS 选择器#sb_form_q更稳定即使前端 ID 变了只要 placeholder 文本没变脚本依然能运行。Playwright 内置了一系列GetBy方法Role, Text, Label, Placeholder, AltText 等应作为首选。WaitForAsync: Playwright 的自动等待机制非常强大。大多数操作如ClickAsync,FillAsync内部都会等待元素可操作。但对于像等待导航完成、等待动态加载的元素显式使用WaitForURLAsync或WaitForAsync能让脚本更健壮。运行这个脚本 (dotnet run)你将看到浏览器自动执行搜索并输出结果。恭喜你已经迈出了第一步4. 核心概念与 API 深度解析理解了基本流程后我们需要深入几个核心概念这是写出高质量 Playwright 脚本的基石。4.1 定位器Locator与元素交互的艺术定位器是 Playwright 中用于查找和操作页面元素的句柄。它的设计目标是可重试性和稳定性。1. 定位策略优先级从高到低语义化定位器GetByRole,GetByText,GetByLabel,GetByPlaceholder,GetByAltText。这些与页面内容绑定最不易受前端结构变化影响。// 最佳实践使用 Role 和 Text await page.GetByRole(AriaRole.Button, new() { Name 提交 }).ClickAsync(); await page.GetByText(确认订单).ClickAsync();CSS 或 XPath 定位器 当语义化定位器不适用时使用。Playwright 支持标准的 CSS 选择器和 XPath。// CSS 选择器 var listItems page.Locator(.product-list li); // XPath (谨慎使用通常有更好的替代方案) var specificItem page.Locator(//button[data-testidsubmit]);Frame内的定位 对于 iframe 中的元素必须先定位到 frame。var frame page.FrameByUrl(**/login-frame); await frame.GetByPlaceholder(用户名).FillAsync(user);2. 定位器操作链定位器支持链式调用使得代码非常清晰。await page .GetByRole(AriaRole.List) // 找到一个列表 .Locator(li) // 在这个列表内找所有 li 元素 .Filter(new() { HasText 重要 }) // 过滤出包含“重要”文本的 li .First // 取第一个 .ClickAsync();4.2 自动等待与显式等待Playwright 的操作是“智能”的。当你执行ClickAsync()时它会自动执行一系列检查等待元素出现在 DOM 中。等待元素可见非隐藏非display: none, 非visibility: hidden。等待元素稳定例如停止动画。等待元素可交互例如未被其他元素遮挡。滚动元素到视图中。最后才执行点击。这意味着你大多数时候不需要写Task.Delay或Thread.Sleep。这是它比 Selenium 稳定得多的主要原因。何时需要显式等待等待导航await page.WaitForURLAsync(**/dashboard)。等待特定状态await page.WaitForLoadStateAsync(LoadState.NetworkIdle)等待网络空闲。等待自定义条件await page.WaitForFunctionAsync(() document.readyState complete)。等待元素满足复杂条件await element.WaitForAsync(new LocatorWaitForOptions { State WaitForSelectorState.Attached, Timeout 10000 })。避坑技巧 如果脚本在 CI/CD 环境中失败但在本地成功很可能是等待时间不足。可以全局增加超时时间playwright.DefaultTimeout 60000; // 60秒。但更好的方法是优化等待条件使用WaitFor等待特定内容出现而不是盲目增加超时。4.3 浏览器上下文BrowserContext与多页面管理BrowserContext是一个独立于其他上下文的“隐身”会话。它拥有独立的 cookies、缓存、本地存储和权限设置。这个特性极其有用场景一模拟不同用户// 用户A的上下文 var contextA await browser.NewContextAsync(); var pageA await contextA.NewPageAsync(); // ... 用户A登录操作 // 用户B的完全独立上下文 var contextB await browser.NewContextAsync(); var pageB await contextB.NewPageAsync(); // ... 用户B的操作不会共享用户A的登录态场景二设备模拟与权限设置var iPhone playwright.Devices[iPhone 13]; var mobileContext await browser.NewContextAsync(new BrowserNewContextOptions { ViewportSize iPhone.Viewport, UserAgent iPhone.UserAgent, Permissions [geolocation] // 授予地理位置权限 }); var mobilePage await mobileContext.NewPageAsync(); await mobilePage.GotoAsync(https://maps.example.com); // 页面将拥有地理位置权限并以移动端样式打开场景三并行测试在测试中可以为每个测试用例创建独立的 Context实现完美的隔离避免测试间相互污染。4.4 处理弹窗、对话框和下载Playwright 可以轻松监听并处理各种浏览器对话框和弹出窗口。处理对话框Alert, Confirm, Prompt// 在触发对话框的操作之前先设置监听器 page.Dialog async (sender, dialog) { Console.WriteLine($对话框类型: {dialog.Type}, 消息: {dialog.Message}); if (dialog.Type DialogType.Alert) { await dialog.AcceptAsync(); // 点击确定 } else if (dialog.Type DialogType.Confirm) { await dialog.DismissAsync(); // 点击取消 } else if (dialog.Type DialogType.Prompt) { await dialog.AcceptAsync(这是输入的值); // 输入值并确定 } }; // 然后执行会触发对话框的操作例如点击一个按钮 await page.GetByText(删除).ClickAsync();处理新窗口/标签页// 监听新页面打开事件 var newPageTask page.WaitForPopupAsync(); // 返回一个 TaskIPage await page.GetByText(在新窗口打开).ClickAsync(); // 这个操作会打开新窗口 var popup await newPageTask; // 等待并获取新页面的引用 await popup.WaitForLoadStateAsync(); Console.WriteLine(await popup.TitleAsync());监听和处理文件下载// 启动下载监听 var downloadTask page.WaitForDownloadAsync(); await page.GetByText(导出报表).ClickAsync(); var download await downloadTask; // 获取下载的文件名和路径 string fileName download.SuggestedFilename; // 指定保存路径 string savePath Path.Combine(downloads, fileName); await download.SaveAsAsync(savePath); Console.WriteLine($文件已下载到: {savePath});5. 高级特性与实战技巧掌握了基础之后让我们探索一些能极大提升脚本能力和效率的高级特性。5.1 网络拦截与模拟MockingPlaywright 允许你拦截和修改网络请求这对于测试边缘情况、模拟慢速网络或第三方 API 响应非常有用。拦截请求并修改响应// 在创建页面或导航之前设置路由 await page.RouteAsync(**/api/user/profile, async route { // 可以检查请求 if (route.Request.Method GET) { // 构造一个模拟的 JSON 响应 var mockResponse new { name Mock User, role Admin }; string json System.Text.Json.JsonSerializer.Serialize(mockResponse); // 用模拟数据完成请求不发送到真实服务器 await route.FulfillAsync(new RouteFulfillOptions { Status 200, ContentType application/json, Body json }); } else { // 其他方法继续正常请求 await route.ContinueAsync(); } }); // 现在导航到页面页面中对 /api/user/profile 的 GET 请求将收到我们的模拟数据 await page.GotoAsync(https://app.example.com/dashboard);拦截请求并记录或修改// 记录所有请求的 URL 和状态 page.Request (sender, request) Console.WriteLine($请求: {request.Method} {request.Url}); page.Response (sender, response) Console.WriteLine($响应: {response.Status} {response.Url}); // 修改请求头例如添加认证令牌 await page.RouteAsync(**/*, async route { var headers new Dictionarystring, string(route.Request.Headers) { [Authorization] Bearer fake-token-for-test }; await route.ContinueAsync(new RouteContinueOptions { Headers headers }); });5.2 执行 JavaScript 与获取页面状态虽然 Playwright 的 API 已经很全面但有时你仍然需要直接执行 JavaScript 来获取复杂的数据或操作 DOM。在页面上下文中执行 JS// 获取页面全局变量或执行计算 var windowSize await page.EvaluateAsyncdynamic(() ({ width: window.innerWidth, height: window.innerHeight })); Console.WriteLine($视口大小: {windowSize.width}x{windowSize.height}); // 获取元素属性比用 Locator 获取更灵活 var allLinks await page.EvaluateAsyncstring[]( () Array.from(document.querySelectorAll(a)).map(a a.href) ); // 在元素句柄的上下文中执行 JS var button page.GetByRole(AriaRole.Button, new() { Name 动态按钮 }); var isDisabled await button.EvaluateAsyncbool(element element.disabled);将 .NET 对象传入 JS 上下文var dataToInject new { key value, count 42 }; await page.EvaluateAsync(data window.myAppConfig data, dataToInject); // 现在页面中的 JavaScript 可以访问 window.myAppConfig5.3 截图、录屏与追踪Playwright 提供了强大的可视化工具用于调试和生成报告。截图// 全屏截图 await page.ScreenshotAsync(new PageScreenshotOptions { Path fullpage.png, FullPage true }); // 元素截图 var element page.Locator(.hero-banner); await element.ScreenshotAsync(new LocatorScreenshotOptions { Path banner.png }); // 指定区域截图 await page.ScreenshotAsync(new PageScreenshotOptions { Path area.png, Clip new Clip { X 10, Y 10, Width 300, Height 200 } });录制视频仅在无头模式下可用var context await browser.NewContextAsync(new BrowserNewContextOptions { RecordVideoDir videos/, // 指定视频保存目录 RecordVideoSize new RecordVideoSize { Width 1920, Height 1080 } }); var page await context.NewContextAsync(); // ... 你的操作 ... await context.CloseAsync(); // 关闭上下文时视频文件会自动保存生成追踪文件Trace追踪文件是 Playwright 最强大的调试工具它记录了脚本执行过程中所有操作、网络请求、控制台日志的快照可以离线在 Trace Viewer 中可视化回放。await context.Tracing.StartAsync(new TracingStartOptions { Screenshots true, Snapshots true, Sources true }); // ... 执行你的测试或操作 ... await context.Tracing.StopAsync(new TracingStopOptions { Path trace.zip });之后你可以使用命令playwright show-trace trace.zip打开一个图形化界面逐帧查看执行过程这对于排查“为什么这里没点击上”这类问题 invaluable。5.4 与测试框架集成NUnit/xUnit/MSTest将 Playwright 集成到现有的 .NET 测试框架中可以更好地组织测试用例利用测试框架的断言、生命周期管理和报告功能。一个典型的 NUnit 测试示例using Microsoft.Playwright; using Microsoft.Playwright.NUnit; using NUnit.Framework; namespace PlaywrightDemo.Tests; [TestFixture] public class LoginTests : PageTest // 继承自 PageTest它提供了 Page, Context, Browser 等便捷属性 { [SetUp] public async Task Setup() { // PageTest 基类已经初始化了 Browser 和 Context // 这里可以进行一些通用设置比如导航到基础URL await Page.GotoAsync(https://demo.app.com); } [Test] public async Task SuccessfulLogin_ShouldNavigateToDashboard() { // 使用 Page来自基类 await Page.GetByPlaceholder(邮箱).FillAsync(userexample.com); await Page.GetByPlaceholder(密码).FillAsync(securepassword); await Page.GetByRole(AriaRole.Button, new() { Name 登录 }).ClickAsync(); // 使用 NUnit 断言 await Expect(Page).ToHaveURLAsync(**/dashboard); await Expect(Page.GetByText(欢迎回来)).ToBeVisibleAsync(); // 或者使用传统的 NUnit Assert var title await Page.TitleAsync(); Assert.That(title, Does.Contain(控制面板)); } [Test] public async Task LoginWithInvalidCredentials_ShouldShowErrorMessage() { await Page.GetByPlaceholder(邮箱).FillAsync(wrongemail.com); await Page.GetByPlaceholder(密码).FillAsync(wrong); await Page.GetByRole(AriaRole.Button, new() { Name 登录 }).ClickAsync(); var errorMessage Page.GetByText(邮箱或密码错误); await Expect(errorMessage).ToBeVisibleAsync(); // 也可以检查元素的 CSS 属性 await Expect(errorMessage).ToHaveCSSAsync(color, rgb(255, 0, 0)); } [TearDown] public async Task TearDown() { // 每个测试后可以清理状态比如退出登录 // 但 PageTest 基类默认会为每个测试创建新的 Context所以通常不需要手动清理 } }使用PageTest基类和[Parallelizable]属性可以轻松实现测试的并行执行每个测试都在独立的 BrowserContext 中运行互不干扰。6. 性能优化与最佳实践当你的自动化脚本变得越来越复杂或者需要在 CI/CD 流水线中运行时性能和稳定性就成为关键。6.1 启动与执行优化复用浏览器实例 在测试套件开始时启动一个浏览器实例在所有测试间共享但为每个测试创建独立的BrowserContext。这比每个测试都启动/关闭浏览器要快得多。// 在测试套件初始化时 static IPlaywright _playwright; static IBrowser _browser; [OneTimeSetUp] public static async Task GlobalSetup() { _playwright await Playwright.CreateAsync(); _browser await _playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions { Headless true }); } [SetUp] public async Task TestSetup() { // 每个测试获取自己的 Context 和 Page var context await _browser.NewContextAsync(); Page await context.NewPageAsync(); }使用无头模式Headless 在 CI/CD 环境或不需要视觉反馈时始终使用Headless true。这能节省大量资源并提升速度。避免不必要的导航 如果多个测试依赖于同一个初始状态如登录考虑使用BeforeAll钩子只登录一次然后每个测试使用新的 Context 但复用相同的存储状态cookies, localStorage。// 获取登录后的存储状态 var storageState await loggedInContext.StorageStateAsync(); // 在新测试的 Context 中注入该状态 var newContext await browser.NewContextAsync(new BrowserNewContextOptions { StorageState storageState });6.2 编写健壮的选择器这是减少脚本“脆性”的最重要实践。使用>await page.GetByTestId(login-submit).ClickAsync();避免使用索引定位page.Locator(div button).Nth(3)非常脆弱页面结构微调就会导致失败。尽量使用文本内容、角色或测试ID。利用Filter和Has 当一组相似元素中需要定位特定一个时使用Filter或Has进行筛选。// 找到包含特定文本的列表项 await page.GetByRole(AriaRole.Listitem).Filter(new() { HasText 待付款 }).ClickAsync(); // 找到内部包含某个子元素的父元素 await page.GetByRole(AriaRole.Row).Filter(new() { Has page.GetByText(异常状态) }).ClickAsync();6.3 错误处理与日志良好的错误处理和日志能让你在脚本失败时快速定位问题。try { // 尝试进行一个可能失败的操作 await page.GetByText(瞬态按钮).ClickAsync(new LocatorClickOptions { Timeout 5000 }); // 设置较短超时 } catch (TimeoutException ex) { // 记录详细上下文 Console.WriteLine($点击‘瞬态按钮’超时。当前URL: {page.Url}); Console.WriteLine($页面HTML片段: {await page.ContentAsync().Substring(0, 1000)}); // 尝试备用方案或记录错误后继续 await page.ScreenshotAsync(new PageScreenshotOptions { Path error_screenshot.png, FullPage true }); // 或者重新加载页面重试 await page.ReloadAsync(); // 根据业务逻辑决定是抛出异常还是继续 throw new Exception(关键操作失败终止流程。, ex); }考虑使用像 Serilog 这样的日志库将日志结构化输出到文件或集中式日志系统便于在 CI/CD 中分析。7. 集成到 CI/CD 流水线将 Playwright 测试集成到 GitHub Actions、Azure DevOps 或 Jenkins 等 CI/CD 工具中可以实现自动化测试和回归验证。一个典型的 GitHub Actions 工作流配置 (.github/workflows/playwright.yml)name: Playwright Tests on: [push, pull_request] jobs: test: timeout-minutes: 60 runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-dotnetv3 with: dotnet-version: 8.x - name: 安装依赖 run: dotnet restore - name: 安装 Playwright 浏览器 run: | dotnet tool update --global Microsoft.Playwright.CLI playwright install --with-deps chromium # 在CI中通常只安装一个浏览器以加快速度 - name: 运行 Playwright 测试 run: dotnet test --configuration Release --verbosity normal env: # 如果测试需要环境变量在这里设置 BASE_URL: ${{ secrets.BASE_URL }} - name: 上传测试结果如果测试框架生成 if: always() # 即使测试失败也上传 uses: actions/upload-artifactv3 with: name: test-results path: ./TestResults/ - name: 上传追踪和视频如果生成 if: always() uses: actions/upload-artifactv3 with: name: playwright-traces path: ./**/test-results/ # 假设你的测试输出目录关键点--with-deps: 在 Linux CI 环境中这个参数确保安装所有必要的系统依赖如库文件。只安装必要浏览器 CI 环境中为了速度通常只安装 Chromium。if: always(): 确保测试失败时追踪文件和截图等诊断信息也能被上传方便排查。使用 Secrets 将测试环境的 URL、登录凭证等敏感信息存储在 CI/CD 平台的 Secrets 中而不是硬编码在代码里。8. 常见问题与排查指南即使遵循了最佳实践在实际操作中仍会遇到问题。这里记录了一些常见“坑”及其解决方案。问题现象可能原因排查步骤与解决方案TimeoutException频繁发生1. 网络慢或页面加载慢。2. 元素定位器不稳定在超时时间内未出现。3. 页面有动画或动态内容导致元素状态不稳定。1. 增加全局或局部超时playwright.DefaultTimeout 60000。2.优先检查定位器使用 Playwright Inspector (playwright codegen) 重新生成定位器或使用page.Locator(‘your-selector’).WaitForAsync()先确保元素存在。3. 使用WaitForLoadState(LoadState.NetworkIdle)等待网络空闲。4. 使用WaitForFunction等待特定的 JS 条件成立。脚本在本地运行成功在 CI/CD 失败1. CI 环境与本地环境差异浏览器版本、屏幕分辨率、时区。2. CI 环境资源CPU/内存不足。3. 网络延迟或外部依赖服务在 CI 环境不可达。1. 确保 CI 使用固定的浏览器版本在playwright.config.json中配置channel或使用playwright install安装特定版本。2. 在 CI 脚本中增加资源检查和等待时间。3. 使用page.Request和page.Response事件监听器记录网络请求检查是否有请求失败。4. 在 CI 中启用视频录制和追踪失败后分析录像。元素无法点击或交互1. 元素被其他元素遮挡弹窗、遮罩层。2. 元素处于不可交互状态disabled, hidden。3. 坐标点击不准确。1. 使用page.Screenshot在点击前截图查看遮挡情况。2. 检查元素状态await element.IsEnabledAsync()await element.IsVisibleAsync()。3. 使用Locator.ClickAsync而非基于坐标的点击Playwright 会自动滚动并确保元素可点。4. 尝试强制点击不推荐作为首选await element.ClickAsync(new LocatorClickOptions { Force true });。iframe 内的元素找不到未切换到正确的 iframe 上下文。1. 先定位 iframe 元素var frame page.FrameLocator(‘iframe#id’)或page.FrameByUrl(‘**/frame-content’)。2. 在 frame 对象上使用定位器await frame.GetByText(‘按钮’).ClickAsync()。切勿在page上直接定位 iframe 内的元素。下载文件失败或找不到1. 下载未触发或路径错误。2. 浏览器设置了默认下载路径未监听下载事件。1. 确保在触发下载的操作之前设置page.WaitForDownloadAsync()监听。2. 使用Download.SuggestedFilename获取文件名并用Download.SaveAsAsync(path)指定保存路径避免依赖浏览器默认路径。浏览器启动失败1. 浏览器未安装或安装损坏。2. 端口冲突或已有浏览器进程残留。3. 系统依赖缺失Linux 常见。1. 运行playwright install重新安装浏览器。2. 检查任务管理器结束残留的浏览器进程。3. 在 Linux 上使用playwright install --with-deps安装系统依赖。查看 Playwright 官方文档的 Troubleshooting 章节。最后的建议 当遇到难以解决的问题时生成追踪文件Trace是最有效的调试手段。它让你能像看录像一样回放整个测试过程查看每一步的页面快照、网络请求和 console 日志绝大多数问题都能通过分析 Trace 找到根源。
.NET开发者指南：Playwright自动化测试从入门到实战
1. 项目概述为什么是 Playwright for .NET如果你是一名 .NET 开发者正在为 Web 自动化测试、爬虫或者 RPA机器人流程自动化项目寻找一个可靠的工具那么 Playwright for .NET 绝对值得你投入时间。我最初接触它是因为厌倦了 Selenium 那令人头疼的浏览器驱动管理和偶发性的不稳定。Playwright 由微软出品专为现代 Web 应用设计它原生支持 Chromium、Firefox 和 WebKit 三大浏览器引擎并且提供了跨平台、跨语言的统一 API。对于 .NET 开发者来说这意味着你可以用熟悉的 C# 语言在 Visual Studio 或 Rider 里编写出强大、稳定且执行速度极快的自动化脚本。简单来说Playwright for .NET 解决了几个核心痛点浏览器兼容性一套脚本跑遍三大内核、执行稳定性内置智能等待告别脆弱的Thread.Sleep、开发体验强大的录制工具和调试能力以及性能支持无头模式和多浏览器上下文并行。无论是为你的 ASP.NET Core 应用做端到端测试还是需要自动化处理一些网页数据它都能成为你得力的“数字员工”。接下来我将从一个 .NET 开发者的实战视角带你从零开始深入掌握 Playwright for .NET 的方方面面。2. 环境准备与项目初始化在开始编写第一行代码之前正确的环境搭建是成功的第一步。这个过程比想象中要简单但有些细节不注意后面可能会踩坑。2.1 安装 .NET SDK 与创建项目首先确保你的开发机上安装了 .NET 6 或更高版本的 SDK。你可以通过命令行dotnet --version来检查。我推荐使用最新的 LTS 版本以获得最好的性能和兼容性。创建一个新的控制台应用项目作为我们的 playground 是最佳起点dotnet new console -n PlaywrightDemo cd PlaywrightDemo2.2 安装 Playwright NuGet 包接下来通过 NuGet 包管理器安装 Playwright。这里有两个关键包Microsoft.Playwright 这是核心库包含了所有的 API。Microsoft.Playwright.NUnit或Microsoft.Playwright.MSTest 如果你计划将 Playwright 用于单元测试框架这是非常常见的用法需要安装对应的测试适配器。这里我们以 NUnit 为例因为它与 Playwright 的集成非常流畅。使用 .NET CLI 安装dotnet add package Microsoft.Playwright dotnet add package Microsoft.Playwright.NUnit注意 安装Microsoft.Playwright包时它会在项目目录下引入一个Drivers文件夹里面包含了 Playwright 的工具脚本。但这并不会自动安装浏览器。浏览器安装是一个独立的步骤。2.3 安装浏览器二进制文件这是 Playwright 设计上非常聪明的一点它将浏览器管理与代码依赖分离。你需要通过 Playwright 提供的 CLI 工具来安装所需的浏览器。这确保了团队中所有成员、CI/CD 流水线使用的浏览器版本完全一致。在项目根目录下执行dotnet tool update --global Microsoft.Playwright.CLI playwright installplaywright install命令会下载 Chromium、Firefox 和 WebKit 的最新兼容版本。如果你只需要其中某一个可以指定例如playwright install chromium。实操心得 在国内网络环境下下载浏览器可能会非常慢甚至失败。这里有两个解决方案使用镜像源 设置环境变量PLAYWRIGHT_DOWNLOAD_HOST。例如在 PowerShell 中临时设置$env:PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright然后再运行playwright install。这是最推荐的方法。手动下载 如果 CLI 安装失败可以去 GitHub Releases 页面手动下载对应平台的浏览器包解压到用户目录下的特定缓存路径如%USERPROFILE%\AppData\Local\ms-playwrighton Windows。不过手动管理版本比较麻烦优先推荐镜像方案。至此你的 .NET 项目已经准备好了所有必要的依赖。接下来让我们编写第一个脚本感受一下 Playwright 的流畅。3. 第一个脚本从录制到理解对于新手最快上手的方式莫过于使用 Playwright 的录制功能。它能将你的浏览器操作直接转换成 C# 代码。3.1 使用 Codegen 录制脚本在项目目录下打开终端运行playwright codegen https://www.bing.com这会自动打开两个窗口一个浏览器窗口和一个 Playwright Inspector 窗口。你在浏览器里的所有操作点击、输入、导航都会被实时转换成代码显示在 Inspector 里并且你可以选择生成 C# 代码。例如你去 Bing 首页在搜索框输入“Playwright .NET”然后点击搜索按钮。Inspector 会生成类似如下的代码// 这是录制生成的代码框架 await page.GotoAsync(https://www.bing.com/); await page.Locator(input[nameq]).ClickAsync(); await page.Locator(input[nameq]).FillAsync(Playwright .NET); await page.Locator(input[nameq]).PressAsync(Enter);录制结束后你可以将这些代码复制到你的Program.cs中。但千万不要止步于此。录制的代码是一个很好的起点但往往不够健壮比如使用了脆弱的 CSS 选择器和结构化。我们的目标是理解并优化它。3.2 编写结构化的第一个脚本让我们抛开录制手动编写一个更健壮、可读性更好的版本。创建一个新的BasicAutomation.cs文件using Microsoft.Playwright; class BasicAutomation { public static async Task Main() { // 1. 创建 Playwright 实例 using var playwright await Playwright.CreateAsync(); // 2. 启动浏览器这里以 Chromium 无头模式为例 await using var browser await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions { Headless false // 设置为 true 则不显示浏览器界面适合 CI/CD }); // 3. 创建浏览器上下文Context和页面Page // Context 相当于一个独立的会话可以隔离 cookies、localStorage 等 var context await browser.NewContextAsync(); var page await context.NewPageAsync(); // 4. 导航到目标页面 await page.GotoAsync(https://www.bing.com); Console.WriteLine($页面标题: {await page.TitleAsync()}); // 5. 定位元素并交互 - 使用更可靠的定位器 // 优先使用 getByRole, getByText, getByPlaceholder 等语义化定位器 var searchBox page.GetByPlaceholder(搜索网页); await searchBox.ClickAsync(); await searchBox.FillAsync(Playwright for .NET); await searchBox.PressAsync(Enter); // 6. 等待导航完成并获取结果 await page.WaitForURLAsync(**/search?qPlaywright.NET**); // 等待搜索结果元素出现 var firstResult page.Locator(#b_results li.b_algo h2 a).First; await firstResult.WaitForAsync(new LocatorWaitForOptions { State WaitForSelectorState.Attached }); Console.WriteLine($第一个结果标题: {await firstResult.TextContentAsync()}); // 7. 可选截图 await page.ScreenshotAsync(new PageScreenshotOptions { Path search_results.png }); Console.WriteLine(自动化任务完成。); // 浏览器和上下文会在 using 块结束时自动关闭 } }关键点解析Playwright.CreateAsync(): 这是所有操作的起点管理着浏览器驱动。LaunchAsync: 启动浏览器进程。Headless: false让你能看到操作过程便于调试。BrowserContext: 这是一个核心概念。每个 Context 是独立的你可以用它来模拟不同的用户会话、设备如手机/平板或设置不同的权限如地理定位、通知。这对于测试多用户场景或需要登录态隔离的情况至关重要。Page: 代表一个标签页。定位器Locator: 这是 Playwright 的精华。page.GetByPlaceholder(...)是推荐的方式它比直接写 CSS 选择器#sb_form_q更稳定即使前端 ID 变了只要 placeholder 文本没变脚本依然能运行。Playwright 内置了一系列GetBy方法Role, Text, Label, Placeholder, AltText 等应作为首选。WaitForAsync: Playwright 的自动等待机制非常强大。大多数操作如ClickAsync,FillAsync内部都会等待元素可操作。但对于像等待导航完成、等待动态加载的元素显式使用WaitForURLAsync或WaitForAsync能让脚本更健壮。运行这个脚本 (dotnet run)你将看到浏览器自动执行搜索并输出结果。恭喜你已经迈出了第一步4. 核心概念与 API 深度解析理解了基本流程后我们需要深入几个核心概念这是写出高质量 Playwright 脚本的基石。4.1 定位器Locator与元素交互的艺术定位器是 Playwright 中用于查找和操作页面元素的句柄。它的设计目标是可重试性和稳定性。1. 定位策略优先级从高到低语义化定位器GetByRole,GetByText,GetByLabel,GetByPlaceholder,GetByAltText。这些与页面内容绑定最不易受前端结构变化影响。// 最佳实践使用 Role 和 Text await page.GetByRole(AriaRole.Button, new() { Name 提交 }).ClickAsync(); await page.GetByText(确认订单).ClickAsync();CSS 或 XPath 定位器 当语义化定位器不适用时使用。Playwright 支持标准的 CSS 选择器和 XPath。// CSS 选择器 var listItems page.Locator(.product-list li); // XPath (谨慎使用通常有更好的替代方案) var specificItem page.Locator(//button[data-testidsubmit]);Frame内的定位 对于 iframe 中的元素必须先定位到 frame。var frame page.FrameByUrl(**/login-frame); await frame.GetByPlaceholder(用户名).FillAsync(user);2. 定位器操作链定位器支持链式调用使得代码非常清晰。await page .GetByRole(AriaRole.List) // 找到一个列表 .Locator(li) // 在这个列表内找所有 li 元素 .Filter(new() { HasText 重要 }) // 过滤出包含“重要”文本的 li .First // 取第一个 .ClickAsync();4.2 自动等待与显式等待Playwright 的操作是“智能”的。当你执行ClickAsync()时它会自动执行一系列检查等待元素出现在 DOM 中。等待元素可见非隐藏非display: none, 非visibility: hidden。等待元素稳定例如停止动画。等待元素可交互例如未被其他元素遮挡。滚动元素到视图中。最后才执行点击。这意味着你大多数时候不需要写Task.Delay或Thread.Sleep。这是它比 Selenium 稳定得多的主要原因。何时需要显式等待等待导航await page.WaitForURLAsync(**/dashboard)。等待特定状态await page.WaitForLoadStateAsync(LoadState.NetworkIdle)等待网络空闲。等待自定义条件await page.WaitForFunctionAsync(() document.readyState complete)。等待元素满足复杂条件await element.WaitForAsync(new LocatorWaitForOptions { State WaitForSelectorState.Attached, Timeout 10000 })。避坑技巧 如果脚本在 CI/CD 环境中失败但在本地成功很可能是等待时间不足。可以全局增加超时时间playwright.DefaultTimeout 60000; // 60秒。但更好的方法是优化等待条件使用WaitFor等待特定内容出现而不是盲目增加超时。4.3 浏览器上下文BrowserContext与多页面管理BrowserContext是一个独立于其他上下文的“隐身”会话。它拥有独立的 cookies、缓存、本地存储和权限设置。这个特性极其有用场景一模拟不同用户// 用户A的上下文 var contextA await browser.NewContextAsync(); var pageA await contextA.NewPageAsync(); // ... 用户A登录操作 // 用户B的完全独立上下文 var contextB await browser.NewContextAsync(); var pageB await contextB.NewPageAsync(); // ... 用户B的操作不会共享用户A的登录态场景二设备模拟与权限设置var iPhone playwright.Devices[iPhone 13]; var mobileContext await browser.NewContextAsync(new BrowserNewContextOptions { ViewportSize iPhone.Viewport, UserAgent iPhone.UserAgent, Permissions [geolocation] // 授予地理位置权限 }); var mobilePage await mobileContext.NewPageAsync(); await mobilePage.GotoAsync(https://maps.example.com); // 页面将拥有地理位置权限并以移动端样式打开场景三并行测试在测试中可以为每个测试用例创建独立的 Context实现完美的隔离避免测试间相互污染。4.4 处理弹窗、对话框和下载Playwright 可以轻松监听并处理各种浏览器对话框和弹出窗口。处理对话框Alert, Confirm, Prompt// 在触发对话框的操作之前先设置监听器 page.Dialog async (sender, dialog) { Console.WriteLine($对话框类型: {dialog.Type}, 消息: {dialog.Message}); if (dialog.Type DialogType.Alert) { await dialog.AcceptAsync(); // 点击确定 } else if (dialog.Type DialogType.Confirm) { await dialog.DismissAsync(); // 点击取消 } else if (dialog.Type DialogType.Prompt) { await dialog.AcceptAsync(这是输入的值); // 输入值并确定 } }; // 然后执行会触发对话框的操作例如点击一个按钮 await page.GetByText(删除).ClickAsync();处理新窗口/标签页// 监听新页面打开事件 var newPageTask page.WaitForPopupAsync(); // 返回一个 TaskIPage await page.GetByText(在新窗口打开).ClickAsync(); // 这个操作会打开新窗口 var popup await newPageTask; // 等待并获取新页面的引用 await popup.WaitForLoadStateAsync(); Console.WriteLine(await popup.TitleAsync());监听和处理文件下载// 启动下载监听 var downloadTask page.WaitForDownloadAsync(); await page.GetByText(导出报表).ClickAsync(); var download await downloadTask; // 获取下载的文件名和路径 string fileName download.SuggestedFilename; // 指定保存路径 string savePath Path.Combine(downloads, fileName); await download.SaveAsAsync(savePath); Console.WriteLine($文件已下载到: {savePath});5. 高级特性与实战技巧掌握了基础之后让我们探索一些能极大提升脚本能力和效率的高级特性。5.1 网络拦截与模拟MockingPlaywright 允许你拦截和修改网络请求这对于测试边缘情况、模拟慢速网络或第三方 API 响应非常有用。拦截请求并修改响应// 在创建页面或导航之前设置路由 await page.RouteAsync(**/api/user/profile, async route { // 可以检查请求 if (route.Request.Method GET) { // 构造一个模拟的 JSON 响应 var mockResponse new { name Mock User, role Admin }; string json System.Text.Json.JsonSerializer.Serialize(mockResponse); // 用模拟数据完成请求不发送到真实服务器 await route.FulfillAsync(new RouteFulfillOptions { Status 200, ContentType application/json, Body json }); } else { // 其他方法继续正常请求 await route.ContinueAsync(); } }); // 现在导航到页面页面中对 /api/user/profile 的 GET 请求将收到我们的模拟数据 await page.GotoAsync(https://app.example.com/dashboard);拦截请求并记录或修改// 记录所有请求的 URL 和状态 page.Request (sender, request) Console.WriteLine($请求: {request.Method} {request.Url}); page.Response (sender, response) Console.WriteLine($响应: {response.Status} {response.Url}); // 修改请求头例如添加认证令牌 await page.RouteAsync(**/*, async route { var headers new Dictionarystring, string(route.Request.Headers) { [Authorization] Bearer fake-token-for-test }; await route.ContinueAsync(new RouteContinueOptions { Headers headers }); });5.2 执行 JavaScript 与获取页面状态虽然 Playwright 的 API 已经很全面但有时你仍然需要直接执行 JavaScript 来获取复杂的数据或操作 DOM。在页面上下文中执行 JS// 获取页面全局变量或执行计算 var windowSize await page.EvaluateAsyncdynamic(() ({ width: window.innerWidth, height: window.innerHeight })); Console.WriteLine($视口大小: {windowSize.width}x{windowSize.height}); // 获取元素属性比用 Locator 获取更灵活 var allLinks await page.EvaluateAsyncstring[]( () Array.from(document.querySelectorAll(a)).map(a a.href) ); // 在元素句柄的上下文中执行 JS var button page.GetByRole(AriaRole.Button, new() { Name 动态按钮 }); var isDisabled await button.EvaluateAsyncbool(element element.disabled);将 .NET 对象传入 JS 上下文var dataToInject new { key value, count 42 }; await page.EvaluateAsync(data window.myAppConfig data, dataToInject); // 现在页面中的 JavaScript 可以访问 window.myAppConfig5.3 截图、录屏与追踪Playwright 提供了强大的可视化工具用于调试和生成报告。截图// 全屏截图 await page.ScreenshotAsync(new PageScreenshotOptions { Path fullpage.png, FullPage true }); // 元素截图 var element page.Locator(.hero-banner); await element.ScreenshotAsync(new LocatorScreenshotOptions { Path banner.png }); // 指定区域截图 await page.ScreenshotAsync(new PageScreenshotOptions { Path area.png, Clip new Clip { X 10, Y 10, Width 300, Height 200 } });录制视频仅在无头模式下可用var context await browser.NewContextAsync(new BrowserNewContextOptions { RecordVideoDir videos/, // 指定视频保存目录 RecordVideoSize new RecordVideoSize { Width 1920, Height 1080 } }); var page await context.NewContextAsync(); // ... 你的操作 ... await context.CloseAsync(); // 关闭上下文时视频文件会自动保存生成追踪文件Trace追踪文件是 Playwright 最强大的调试工具它记录了脚本执行过程中所有操作、网络请求、控制台日志的快照可以离线在 Trace Viewer 中可视化回放。await context.Tracing.StartAsync(new TracingStartOptions { Screenshots true, Snapshots true, Sources true }); // ... 执行你的测试或操作 ... await context.Tracing.StopAsync(new TracingStopOptions { Path trace.zip });之后你可以使用命令playwright show-trace trace.zip打开一个图形化界面逐帧查看执行过程这对于排查“为什么这里没点击上”这类问题 invaluable。5.4 与测试框架集成NUnit/xUnit/MSTest将 Playwright 集成到现有的 .NET 测试框架中可以更好地组织测试用例利用测试框架的断言、生命周期管理和报告功能。一个典型的 NUnit 测试示例using Microsoft.Playwright; using Microsoft.Playwright.NUnit; using NUnit.Framework; namespace PlaywrightDemo.Tests; [TestFixture] public class LoginTests : PageTest // 继承自 PageTest它提供了 Page, Context, Browser 等便捷属性 { [SetUp] public async Task Setup() { // PageTest 基类已经初始化了 Browser 和 Context // 这里可以进行一些通用设置比如导航到基础URL await Page.GotoAsync(https://demo.app.com); } [Test] public async Task SuccessfulLogin_ShouldNavigateToDashboard() { // 使用 Page来自基类 await Page.GetByPlaceholder(邮箱).FillAsync(userexample.com); await Page.GetByPlaceholder(密码).FillAsync(securepassword); await Page.GetByRole(AriaRole.Button, new() { Name 登录 }).ClickAsync(); // 使用 NUnit 断言 await Expect(Page).ToHaveURLAsync(**/dashboard); await Expect(Page.GetByText(欢迎回来)).ToBeVisibleAsync(); // 或者使用传统的 NUnit Assert var title await Page.TitleAsync(); Assert.That(title, Does.Contain(控制面板)); } [Test] public async Task LoginWithInvalidCredentials_ShouldShowErrorMessage() { await Page.GetByPlaceholder(邮箱).FillAsync(wrongemail.com); await Page.GetByPlaceholder(密码).FillAsync(wrong); await Page.GetByRole(AriaRole.Button, new() { Name 登录 }).ClickAsync(); var errorMessage Page.GetByText(邮箱或密码错误); await Expect(errorMessage).ToBeVisibleAsync(); // 也可以检查元素的 CSS 属性 await Expect(errorMessage).ToHaveCSSAsync(color, rgb(255, 0, 0)); } [TearDown] public async Task TearDown() { // 每个测试后可以清理状态比如退出登录 // 但 PageTest 基类默认会为每个测试创建新的 Context所以通常不需要手动清理 } }使用PageTest基类和[Parallelizable]属性可以轻松实现测试的并行执行每个测试都在独立的 BrowserContext 中运行互不干扰。6. 性能优化与最佳实践当你的自动化脚本变得越来越复杂或者需要在 CI/CD 流水线中运行时性能和稳定性就成为关键。6.1 启动与执行优化复用浏览器实例 在测试套件开始时启动一个浏览器实例在所有测试间共享但为每个测试创建独立的BrowserContext。这比每个测试都启动/关闭浏览器要快得多。// 在测试套件初始化时 static IPlaywright _playwright; static IBrowser _browser; [OneTimeSetUp] public static async Task GlobalSetup() { _playwright await Playwright.CreateAsync(); _browser await _playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions { Headless true }); } [SetUp] public async Task TestSetup() { // 每个测试获取自己的 Context 和 Page var context await _browser.NewContextAsync(); Page await context.NewPageAsync(); }使用无头模式Headless 在 CI/CD 环境或不需要视觉反馈时始终使用Headless true。这能节省大量资源并提升速度。避免不必要的导航 如果多个测试依赖于同一个初始状态如登录考虑使用BeforeAll钩子只登录一次然后每个测试使用新的 Context 但复用相同的存储状态cookies, localStorage。// 获取登录后的存储状态 var storageState await loggedInContext.StorageStateAsync(); // 在新测试的 Context 中注入该状态 var newContext await browser.NewContextAsync(new BrowserNewContextOptions { StorageState storageState });6.2 编写健壮的选择器这是减少脚本“脆性”的最重要实践。使用>await page.GetByTestId(login-submit).ClickAsync();避免使用索引定位page.Locator(div button).Nth(3)非常脆弱页面结构微调就会导致失败。尽量使用文本内容、角色或测试ID。利用Filter和Has 当一组相似元素中需要定位特定一个时使用Filter或Has进行筛选。// 找到包含特定文本的列表项 await page.GetByRole(AriaRole.Listitem).Filter(new() { HasText 待付款 }).ClickAsync(); // 找到内部包含某个子元素的父元素 await page.GetByRole(AriaRole.Row).Filter(new() { Has page.GetByText(异常状态) }).ClickAsync();6.3 错误处理与日志良好的错误处理和日志能让你在脚本失败时快速定位问题。try { // 尝试进行一个可能失败的操作 await page.GetByText(瞬态按钮).ClickAsync(new LocatorClickOptions { Timeout 5000 }); // 设置较短超时 } catch (TimeoutException ex) { // 记录详细上下文 Console.WriteLine($点击‘瞬态按钮’超时。当前URL: {page.Url}); Console.WriteLine($页面HTML片段: {await page.ContentAsync().Substring(0, 1000)}); // 尝试备用方案或记录错误后继续 await page.ScreenshotAsync(new PageScreenshotOptions { Path error_screenshot.png, FullPage true }); // 或者重新加载页面重试 await page.ReloadAsync(); // 根据业务逻辑决定是抛出异常还是继续 throw new Exception(关键操作失败终止流程。, ex); }考虑使用像 Serilog 这样的日志库将日志结构化输出到文件或集中式日志系统便于在 CI/CD 中分析。7. 集成到 CI/CD 流水线将 Playwright 测试集成到 GitHub Actions、Azure DevOps 或 Jenkins 等 CI/CD 工具中可以实现自动化测试和回归验证。一个典型的 GitHub Actions 工作流配置 (.github/workflows/playwright.yml)name: Playwright Tests on: [push, pull_request] jobs: test: timeout-minutes: 60 runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-dotnetv3 with: dotnet-version: 8.x - name: 安装依赖 run: dotnet restore - name: 安装 Playwright 浏览器 run: | dotnet tool update --global Microsoft.Playwright.CLI playwright install --with-deps chromium # 在CI中通常只安装一个浏览器以加快速度 - name: 运行 Playwright 测试 run: dotnet test --configuration Release --verbosity normal env: # 如果测试需要环境变量在这里设置 BASE_URL: ${{ secrets.BASE_URL }} - name: 上传测试结果如果测试框架生成 if: always() # 即使测试失败也上传 uses: actions/upload-artifactv3 with: name: test-results path: ./TestResults/ - name: 上传追踪和视频如果生成 if: always() uses: actions/upload-artifactv3 with: name: playwright-traces path: ./**/test-results/ # 假设你的测试输出目录关键点--with-deps: 在 Linux CI 环境中这个参数确保安装所有必要的系统依赖如库文件。只安装必要浏览器 CI 环境中为了速度通常只安装 Chromium。if: always(): 确保测试失败时追踪文件和截图等诊断信息也能被上传方便排查。使用 Secrets 将测试环境的 URL、登录凭证等敏感信息存储在 CI/CD 平台的 Secrets 中而不是硬编码在代码里。8. 常见问题与排查指南即使遵循了最佳实践在实际操作中仍会遇到问题。这里记录了一些常见“坑”及其解决方案。问题现象可能原因排查步骤与解决方案TimeoutException频繁发生1. 网络慢或页面加载慢。2. 元素定位器不稳定在超时时间内未出现。3. 页面有动画或动态内容导致元素状态不稳定。1. 增加全局或局部超时playwright.DefaultTimeout 60000。2.优先检查定位器使用 Playwright Inspector (playwright codegen) 重新生成定位器或使用page.Locator(‘your-selector’).WaitForAsync()先确保元素存在。3. 使用WaitForLoadState(LoadState.NetworkIdle)等待网络空闲。4. 使用WaitForFunction等待特定的 JS 条件成立。脚本在本地运行成功在 CI/CD 失败1. CI 环境与本地环境差异浏览器版本、屏幕分辨率、时区。2. CI 环境资源CPU/内存不足。3. 网络延迟或外部依赖服务在 CI 环境不可达。1. 确保 CI 使用固定的浏览器版本在playwright.config.json中配置channel或使用playwright install安装特定版本。2. 在 CI 脚本中增加资源检查和等待时间。3. 使用page.Request和page.Response事件监听器记录网络请求检查是否有请求失败。4. 在 CI 中启用视频录制和追踪失败后分析录像。元素无法点击或交互1. 元素被其他元素遮挡弹窗、遮罩层。2. 元素处于不可交互状态disabled, hidden。3. 坐标点击不准确。1. 使用page.Screenshot在点击前截图查看遮挡情况。2. 检查元素状态await element.IsEnabledAsync()await element.IsVisibleAsync()。3. 使用Locator.ClickAsync而非基于坐标的点击Playwright 会自动滚动并确保元素可点。4. 尝试强制点击不推荐作为首选await element.ClickAsync(new LocatorClickOptions { Force true });。iframe 内的元素找不到未切换到正确的 iframe 上下文。1. 先定位 iframe 元素var frame page.FrameLocator(‘iframe#id’)或page.FrameByUrl(‘**/frame-content’)。2. 在 frame 对象上使用定位器await frame.GetByText(‘按钮’).ClickAsync()。切勿在page上直接定位 iframe 内的元素。下载文件失败或找不到1. 下载未触发或路径错误。2. 浏览器设置了默认下载路径未监听下载事件。1. 确保在触发下载的操作之前设置page.WaitForDownloadAsync()监听。2. 使用Download.SuggestedFilename获取文件名并用Download.SaveAsAsync(path)指定保存路径避免依赖浏览器默认路径。浏览器启动失败1. 浏览器未安装或安装损坏。2. 端口冲突或已有浏览器进程残留。3. 系统依赖缺失Linux 常见。1. 运行playwright install重新安装浏览器。2. 检查任务管理器结束残留的浏览器进程。3. 在 Linux 上使用playwright install --with-deps安装系统依赖。查看 Playwright 官方文档的 Troubleshooting 章节。最后的建议 当遇到难以解决的问题时生成追踪文件Trace是最有效的调试手段。它让你能像看录像一样回放整个测试过程查看每一步的页面快照、网络请求和 console 日志绝大多数问题都能通过分析 Trace 找到根源。
