BxPlaywright 1.0发布：真实浏览器、流畅BoxLang，专为AI智能体打造

Ortus Solutions 今日宣布 bx-playwright 1.0 正式发布，这是由 Microsoft Playwright 驱动的 BoxLang 流畅浏览器自动化与测试工具。它与 TestBox 7.2 和 ColdBox 8.3 一同发布，将真实浏览器测试直接带入你的测试规格。驱动 Chromium、Firefox 和 WebKit，测试完整用户旅程，渲染 PDF 和图像，并让你的 AI 代理拥有真实浏览器来验证它们构建的 BoxLang 应用。

playwright().browse( ( page ) => {
	page.visit( "/login" )
		.fill( "Email", "[email protected]" )
		.fill( "Password", "secret" )
		.click( "Sign in" )
		.assertPathIs( "/dashboard" )
		.assertSee( "Welcome back" )
		.screenshot( "dashboard.png" )
} )

这就是一次完整的登录检查。它读起来就像你会写在便利贴上的步骤，而每一行都在真实浏览器中运行。🚀

install-bx-module bx-playwright
bxplaywright install

BoxLang 生产力栈现在有了眼睛 👀

BoxLang 是用于构建、现代化和运行应用的软件生产力平台，让开发者与 AI 代理协同工作。我们一直在组装让代理在 BoxLang 上高效工作的各个部分：

BoxLang AI：用于模型、代理、工具和记忆
实时 MCP 文档服务器：让代理读取最新文档，而不是猜测
Skills：教会代理 BoxLang 以及技术栈中每个框架实际如何工作
机器可读的编译器反馈：通过 boxlang check --format json，让代理能够修复自己的错误

这涵盖了编写代码。但一个代理如果写了登录页面却从未打开过它，就没有完成工作。它只是猜的。缺失的一环是让代理和你的测试套件能够打开应用，像用户一样点击浏览，并证明它确实可用。

这就是 bx-playwright。它闭合了整个循环：构建、运行、浏览、断言、修复。原生支持 BoxLang，运行在 JVM 上，无需在旁额外拼装 JavaScript 测试项目。借助 TestBox 7.2 和 ColdBox 8.3，这个浏览器就存在于你已经在写的测试之中。

为什么选择 bx-playwright

流畅且可链式调用。 每个动作都返回页面，因此整个用户旅程就是一个可读的表达式。
智能选择器。 定位用户所见的内容。"Sign in" 会找到按钮，"Email" 会按标签找到字段。需要精确控制？可使用 @name 表示 data-testid、普通 CSS、Playwright 语法，或像 ref=e12 这样的 AI 快照引用。
告别不稳定等待。 断言会重试直到通过或超时（默认 5 秒），因此你无需在测试中到处撒 sleep() 调用。
应有尽有的配置档案。 playwright( "mobile" )、playwright( [ "android", "dark" ] )、playwright( "ci" )。数十种内置的浏览器、屏幕、设备、外观和模式预设，从左到右合并，也可加入你自己的预设。
无需管理 Node 项目。 像安装任何其他 BoxLang 模块一样安装它。安装器会为你获取驱动、Node.js 和浏览器；或者选择 bx-playwright-full，它为每个平台捆绑 Node.js，适用于隔离服务器。
从第一天起就为代理而构建。 令牌高效的快照、BoxLang AI 的现成工具、MCP 服务器、内联 API 帮助、结构化错误和官方 Agent Skills。下文有更多介绍。
免费且开源。 Apache 2.0，包含所有内容。

包含哪些内容 📦

浏览： 导航、点击、输入、表单、上传、拖放、iframe、弹窗和下载，使用 within() 限定作用域，以及带 count()、texts()、nth() 和 filter() 的定位器
断言： 内联的 assertSee()、assertPathIs()、assertVisible() 等，或类似 expect 的匹配器如 toHaveText 和 toBeVisible。将检查包裹在 page.soft() 中可一次性收集所有失败
网络与 API： 拦截、模拟、阻止或修改请求，监听控制台和网络流量，直接测试 HTTP API，并复用已登录会话
质量检查： 使用差异图像进行视觉回归，内置 WCAG 可访问性审计，assertNoConsoleErrors() 以及跨 URL 列表的 assertNoSmoke() 冒烟测试
页面对象、组件和宏： 将页面建模为 PageObject 类，将可复用小部件建模为 PageComponent 类，或使用你自己的宏扩展 API
渲染： 来自真实浏览器引擎的截图、PDF 和渲染后的 HTML，包括 bx:playwrightRender 组件
自动化脚本： 以 .bxs 脚本运行浏览器任务，使用 cron 或 BoxLang 调度器进行调度
Web 应用： 在运行中的 BoxLang 服务器中使用它，并通过 playwrightEnsureBrowser() 从服务器代码中预置浏览器
CLI： install、doctor、codegen、screenshot、pdf、show-trace、mcp 等，支持 bash 补全和 --json 输出
基于 bx-playwright 构建： 在语义化版本控制下提供有文档的公共契约，以及供框架和库使用的 onPageCreate 和 onPlaywrightArtifact 等拦截事件

几个示例：

// Mock an API and block images
page.intercept( "**/api/users" ).respondJson( [ "Luis", "Brad" ] )
page.intercept( "**/*.{png,jpg}" ).abort()

// Visual regression, masking the parts that change
page.assertScreenshotMatches( "dashboard", { fullPage : true, mask : [ "@clock" ] } )

// Accessibility audit
page.assertNoAccessibilityIssues( { exclude : [ "color-contrast" ], impact : "moderate" } )

还能直接从模板中使用现代浏览器引擎进行渲染：

<bx:playwrightRender type="pdf" path="invoice.pdf" format="A4" margin="1cm">
	<h1>Invoice #invoice.id#</h1>
</bx:playwrightRender>

浏览器测试，内置于 TestBox 7.2 和 ColdBox 8.3 ✅

三个版本一同发布，而浏览器是贯穿其中的主线。我们会在各自文章中深入介绍 TestBox 和 ColdBox，这里先略作体验。

为任意 TestBox 测试规格添加 @browser，即可获得 browse()、每个规格隔离的页面，以及会重试的浏览器匹配器。ColdBox 8.3 将同样的能力带入 BaseTestCase，并提供 visitRoute()、assertRouteIs() 等命名路由辅助方法以及已保存会话登录。

@browser
@baseURL( "http://localhost:8080" )
class extends="testbox.system.BaseSpec" {

	function run() {
		describe( "Login", () => {
			it( "signs in", () => {
				browse( ( page ) => {
					page.visit( "/login" )
						.fill( "Email", "[email protected]" )
						.fill( "Password", "secret" )
						.click( "Sign in" )
					expect( page ).toHavePath( "/dashboard" )
				} )
			} )
		} )
	}

}

失败会自带证据：截图、跟踪和视频会附加到测试规格中。看看实际效果：

当浏览器测试失败时，你能准确看到原因：

而在 ColdBox 中，你的浏览器测试规格了解你的应用：

还有更多内容：九个浏览器匹配器、多用户流程、测试规格重试、仅重跑失败项、用 --web-server 在启动测试时一并启动应用，等等。现在就深入了解 TestBox 浏览器测试指南和 ColdBox 浏览器测试指南。

浏览器测试规格是 BoxLang 类，需要 bx-playwright 模块。在没有该模块的 BoxLang 上，它们会被跳过并提示安装。

为 AI 代理而构建 🤖

在这里，bx-playwright 不再只是“测试库”，而成为 BoxLang 上 AI 辅助开发的核心基础设施。

代理真正能读懂的快照

对模型来说，截图成本高昂，而原始 HTML 又充满噪声。bx-playwright 为代理提供紧凑的可访问性树，其中每个交互元素都有一个引用：

println( page.snapshot( options = { mode : "ai" } ) )
// - textbox "Email" [ref=e5]
// - button "Sign in" [ref=e7]

page.fill( "ref=e5", "[email protected]" ).click( "ref=e7" )

代理会像屏幕阅读器一样查看页面，选择一个引用，并精确作用于该元素。令牌更少，无需猜测选择器。

将浏览器作为 BoxLang AI 的工具集

一次调用即可将 Playwright 实例转换为任何 BoxLang AI 代理都能使用的工具：

agent = aiAgent(
	name         : "Browser",
	instructions : "Use the browser tools to complete the task.",
	tools        : playwright( { baseURL : "http://localhost:8080" } ).aiTools()
)

agent.run( "Log in as [email protected] and tell me how many todos I have" )

代理会获得 browser_visit、browser_snapshot、browser_click、browser_fill、browser_select、browser_press、browser_back、browser_text、browser_screenshot 和 browser_close。每个工具都会返回更新后的页面状态，错误会以文本形式返回而不是异常，因此代理可以读取问题所在并自行恢复。使用其他代理框架？aiToolDefinitions() 会以纯定义形式返回相同的工具。

aiTools() 使用 BoxLang AI，因此请一并安装：install-bx-module bx-ai

为你的编码代理提供 Playwright MCP

在 Claude、Cursor、VS Code 或其他 MCP 客户端中工作？一条命令即可提供浏览器服务：

bxplaywright mcp --headless

# Claude Code
claude mcp add playwright -- bxplaywright mcp --headless

添加 --port 8931 可通过 HTTP 共享同一个服务器。你的编码代理现在可以直接从编辑器中驱动浏览器，访问它正在构建的 BoxLang 应用。

代理可加载的 Agent Skills 和文档

七个官方技能教会你的代理浏览、断言、网络、渲染、测试、安装配置和 AI 集成：

npx skills add ortus-boxlang/skills/boxlang-modules/bx-playwright

在 skills.boxlang.io 上浏览这些技能，以及 TestBox 和 ColdBox 浏览器测试技能。完整文档也可通过 llms.txt 获取。

代理能理解的反馈

内联 API 帮助： page.help()、page.help( "fill" ) 和 playwright().help() 会在运行时记录 API，因此代理会查阅它，而不是编造方法。
结构化错误： 每个失败都有 type、message 和 detail，并提供解决指导。Playwright.Timeout 会提示你用 page.snapshot() 检查选择器。Playwright.NotInstalled 会提示你运行 bxplaywright doctor。
机器可读的 CLI： CLI 命令上的 --json 会返回结构化输出和错误，bxplaywright help --json 会描述每个命令。

也为人准备：代码生成

点击操作你的应用，拿回 BoxLang 代码：

bxplaywright codegen http://localhost:8080 --output=login.bxs

即将推出：BxAgents

bx-playwright 也是 BxAgents 的核心组件，这是我们即将推出的、基于 ColdBox 和 BoxLang AI 构建的约定式 AI 代理框架。这意味着使用 BxAgents 构建的代理开箱即得真实浏览器来验证其工作。我们很快会有更多内容分享。👀

从 cbPlaywright 迁移过来？

在 BoxLang 上？bx-playwright 就是前进方向。

开始使用

要求： BoxLang 1.17+ 和 Java 21+。对于浏览器测试规格：TestBox 7.2+；若要使用路由辅助方法，则需要 ColdBox 8.3+。

两个发行版：

bx-playwright（约 4 MB）：使用你机器上的 Node.js 20+，或为你下载并验证一个
bx-playwright-full：为每个平台捆绑 Node.js。适用于离线或受限环境，前提是浏览器产物已提前预置

# Install the module
install-bx-module bx-playwright

# Install the driver, Node.js and Chromium, then verify
bxplaywright install
bxplaywright doctor

# Linux CI: include the system libraries
bxplaywright install chromium --with-deps

你的第一个脚本：

// hello.bxs
playwright().browse( ( page ) => {
	page.visit( "https://boxlang.io" )
	println( page.title() )
	page.screenshot( "boxlang.png" )
} )

boxlang hello.bxs

在 CommandBox 服务器上运行？在服务器首次设置时安装模块：

"onServerInitialInstall": "install bx-playwright --nosave"

完整演练见入门指南。## 资源

bx-playwright： bxplaywright.boxlang.io | GitHub | ForgeBox
AI 集成指南： bxplaywright.boxlang.io/ai
TestBox 7.2： 新特性 | 浏览器测试指南
ColdBox 8.3： 新特性 | 浏览器测试指南
Agent Skills： skills.boxlang.io
BoxLang： boxlang.io | BoxLang 文档 | BoxLang AI
社区： Ortus 社区 Slack
专业支持与咨询： ortussolutions.com/services

你的智能体可以编写代码。现在，它们和你的测试套件可以证明代码确实能够运行。

分类导航