Nstproxy 现已升级为 Nstdata。了解此次变化。
周一至周五 09:00 - 18:00(UTC+08:00) 公司地址
19H MAXGRAND PLAZA NO.3 TAI YAU STREET SAN PO KONG, KOWLOON HONG KONG ©2026 NST LABS TECH LTD. 保留所有权利。
Marcus Chen Product & Network Architect
如何在远程浏览器中捕获可靠的屏幕截图 TL;DR
仅在目标页面及其数据准备就绪后捕获远程浏览器截图。
对于固定浏览器视口使用视口截图,对于完整文档使用全页截图,或对单个元素使用定位器截图。
在图像旁边记录视口大小、页面滚动高度、设备像素比和浏览器配置。
远程屏幕、页面视口、截图像素和实时视图缩放描述不同的测量。
当您希望基于 CSS 像素的尺寸时使用 scale: 'css',并为高 DPR 视觉检查建立单独的测试。
将凭据和私人页面内容排除在共享文档之外。关闭您的捕获页面并结束管理会话。
什么使远程浏览器截图可靠?
可靠的远程浏览器截图展示了预期页面中的预期内容,其布局已知,并且有足够的元数据以重复捕获。在有效的 PNG 中出现空白小部件可能意味着捕获过早,应用程序返回了错误的响应,或覆盖层阻止了渲染。文件的存在证明捕获发生。捕获前的断言确定图像应该展示的内容。 Nstdata Cloud Browser 。
使用受控示例,例如带有标题和延迟准备标记的发布报告。下面的代码中,截图等待 Build 42 ready 以及文档字体准备。在实际发布作业中,还需要等待重要的数据断言。 浏览器自动化调试指南 解释了如何在文档达到比较阶段之前诊断缺少的标记。
该使用哪个截图范围?
选择能回答您问题的最小范围。视口级别的图像可以显示用户的初始视图并确认粘性头部。全页图像显示文档尺寸,并在实际加载时使折叠下证据可见。定位器图像隔离组件并避免其他地方不相关的布局更改。
捕获 Playwright 调用 有效证据 关键变量 视口 page.screenshot()首次查看、对话框或固定导航 宽度、高度、DPR 和滚动位置 全页 page.screenshot({ fullPage: true })文档布局和折叠下的可用内容 文档高度和延迟加载 元素 locator.screenshot()一个图表、面板或收据 定位器唯一性和组件准备情况
如果应用程序从未渲染其内容,则全页截图可能包括一个空的延迟加载区域。虚拟化列表可能仅在其当前视口附近挂载行。测试特定行,并在页面使用虚拟化时单独捕获该段。在固定头部的情况下,应在捕获之前控制已滚动的位置和覆盖状态。 Playwright 截图指南 。
屏幕、视口和像素缩放之间有什么关系?
屏幕分辨率描述了远程显示环境,视口描述了可用的页面内容区域,而 PNG 的尺寸取决于捕获范围和缩放。Nstdata 的 Resolution Fingerprint 控制报告的屏幕和初始浏览器窗口。浏览器界面可能会减少内容区域。调整实时视图会更改预览表示,因此请使用浏览器端检查来确定实际几何形状。 。
在校准布局时,明确像素缩放。CSS 缩放为每个 CSS 像素提供一个图像像素。设备缩放使用设备像素,并可以在更高 DPR 下产生较大的文件。Playwright API 还提醒 setViewportSize() 可能会重置页面上的屏幕大小。在更改视口后记录观察。如果您的目标是测量已启动的管理设置,请省略该覆盖并记录原始几何形状。 Page.setViewportSize 参考 。
如何从同一任务中捕获全页和元素? 连接到已准备好的远程会话或运行本地图形界面测试,然后在捕获两个范围之前断言已知的内容标记。使用 Node.js 22.12 或更高版本和 playwright-core@1.65.1。要在本地执行,首先运行 npx playwright-core install chromium。
步骤 1. 启动一个批准的捕获目标 保存 fixture.mjs 并用 node fixture.mjs 启动它。打开回环中的 /report。它包含一个命名区域并异步加载其准备标记。对于云测试,在远程浏览器可访问的暂存 URL 部署相同的批准页面合约。
import { createServer } from 'node:http' ;
const receipts = new Map ( ) ;
const pages = {
'/report' : '<main style="min-height:1300px"><section aria-label="Release report"><h1>Release report</h1><p id="status"></p></section></main><script>setTimeout(()=>document.querySelector("#status").textContent="Build 42 ready",100)</script>' ,
} ;
createServer ( async ( req , res ) => {
if ( ! Object . hasOwn ( pages , req . url ) ) { res . writeHead ( 404 ) . end ( ) ; return ; }
res . writeHead ( 200 , { 'content-type' : 'text/html; charset=utf-8' } ) ;
res . end ( '<!doctype html><html lang="en"><meta charset="utf-8"><body>' + pages [ req . url ] ) ;
} ) . listen ( Number ( process . env . FIXTURE_PORT || 4173 ) , '127.0.0.1' , function ( ) {
console . log ( 'Fixture listening on ' + this . address ( ) . port ) ;
} ) ;
步骤 2. 准备浏览器连接 保存下面的共享模块。对于托管运行,在 Cloud Browser → Playground 中选择你的工作空间,设置初始 Resolution Fingerprint 并启动。设置 NSTDATA_API_KEY 和 NSTDATA_SESSION_ID 以进行准备好的会话,在需要时可选设置团队字段。托管连接必须在你自己的授权工作空间中使用。截图和几何断言在本地 Chromium 设备中执行。有关如何连接 Playwright 到远程浏览器的信息,请参见 如何连接 Playwright 到远程浏览器 。
const root = 'https://api.nstdata.io/api/v1/cloud-browser' ;
export async function api ( method , path , body ) {
const key = process . env . NSTDATA_API_KEY ;
if ( ! key ) throw new Error ( 'Set NSTDATA_API_KEY' ) ;
const headers = { 'x-api-key' : key } ;
if ( process . env . NSTDATA_TEAM_ID ) headers [ 'x-team-id' ] = process . env . NSTDATA_TEAM_ID ;
if ( body ) headers [ 'content-type' ] = 'application/json' ;
let response ;
try {
response = await fetch ( root + path , {
method , headers , redirect : 'error' ,
body : body ? JSON . stringify ( body ) : undefined ,
signal : AbortSignal . timeout ( 20_000 ) ,
} ) ;
} catch {
throw Object . assign ( new Error ( 'API transport failed; reconcile the original operation' ) , { retryable : true } ) ;
}
const retryable = response . status === 429 || response . status >= 500 ;
let result ;
try { result = await response . json ( ) ; }
catch { throw Object . assign ( new Error ( 'Invalid API JSON' ) , { retryable } ) ; }
if ( ! response . ok || result . err === true || result . success === false ) {
throw Object . assign ( new Error ( ` Cloud Browser API HTTP ${ response . status } ` ) , { retryable } ) ;
}
if ( ! result . data ) throw new Error ( 'Missing API data' ) ;
return result . data ;
}
export async function connection ( id ) {
if ( ! id ) throw new Error ( 'Set NSTDATA_SESSION_ID' ) ;
const path = ` /sessions/ ${ encodeURIComponent ( id ) } ` ;
const session = await api ( 'GET' , path ) ;
if ( session . state !== 'ready' ) throw new Error ( ` Session is ${ session . state } , not ready ` ) ;
const c = await api ( 'POST' , path + '/automation-credentials' ) ;
if ( c . sessionId !== id || ! c . headerName || ! c . accessToken ||
! ( Date . parse ( c . expiresAt ) > Date . now ( ) ) || new URL ( c . cdpUrl ) . protocol !== 'wss:' ) {
throw new Error ( 'Invalid or expired CDP credentials' ) ;
}
return {
endpoint : c . cdpUrl ,
headers : { [ c . headerName ] : c . headerName . toLowerCase ( ) === 'authorization'
? ` Bearer ${ c . accessToken } ` : c . accessToken } ,
} ;
}
export async function endpoint ( ) {
// An isolated local CDP endpoint can test the client without managed credentials.
if ( process . env . LOCAL_CDP_URL ) {
const url = new URL ( process . env . LOCAL_CDP_URL ) ;
if ( ! [ '127.0.0.1' , 'localhost' , '[::1]' ] . includes ( url . hostname ) ) {
throw new Error ( 'LOCAL_CDP_URL must use loopback' ) ;
}
return { endpoint : url . href , headers : { } } ;
}
return connection ( process . env . NSTDATA_SESSION_ID ) ;
}
import { chromium } from 'playwright-core' ;
import { endpoint } from './cloud-api.mjs' ;
export async function runPage ( task , localOptions = { } ) {
const remote = Boolean ( process . env . NSTDATA_SESSION_ID || process . env . LOCAL_CDP_URL ) ;
let browser ;
let page ;
try {
if ( remote ) {
const auth = await endpoint ( ) ;
browser = await chromium . connectOverCDP ( auth . endpoint , {
headers : auth . headers , timeout : 20_000 ,
} ) ;
} else {
browser = await chromium . launch ( ) ;
}
const context = remote ? browser . contexts ( ) [ 0 ] : await browser . newContext ( localOptions ) ;
if ( ! context ) throw new Error ( 'Browser context missing' ) ;
page = await context . newPage ( ) ;
page . setDefaultTimeout ( 10_000 ) ;
await task ( page ) ;
} finally {
try {
await page ?. close ( ) ;
} finally {
await browser ?. close ( ) ;
}
}
}
步骤 3. 运行捕获脚本 保存 screenshots.mjs 并在捕获目录中运行 TARGET_URL=http://127.0.0.1:4173/report node screenshots.mjs。对于托管运行,替换 URL 为批准的目标并提供其凭证变量。截图文件由工作者编写,应存放在私人工件目录中。
import assert from 'node:assert/strict' ;
import { runPage } from './run-page.mjs' ;
await runPage ( async page => {
await page . setViewportSize ( { width : 960 , height : 720 } ) ;
const response = await page . goto ( new URL ( process . env . TARGET_URL ) . href ) ;
assert ( response ?. ok ( ) ) ;
const report = page . getByRole ( 'region' , { name : 'Release report' } ) ;
await report . getByText ( 'Build 42 ready' , { exact : true } ) . waitFor ( ) ;
await page . evaluate ( ( ) => document . fonts . ready . then ( ( ) => undefined ) ) ;
const geometry = await page . evaluate ( ( ) => ( {
viewport : [ innerWidth , innerHeight ] ,
screen : [ screen . width , screen . height ] ,
dpr : devicePixelRatio ,
documentHeight : document . documentElement . scrollHeight ,
} ) ) ;
const options = { animations : 'disabled' , scale : 'css' } ;
const full = await page . screenshot ( { ... options , fullPage : true , path : 'release-full.png' } ) ;
const element = await report . screenshot ( { ... options , path : 'release-card.png' } ) ;
const dimensions = image => [ image . readUInt32BE ( 16 ) , image . readUInt32BE ( 20 ) ] ;
assert . equal ( dimensions ( full ) [ 0 ] , geometry . viewport [ 0 ] ) ;
assert ( dimensions ( full ) [ 1 ] >= geometry . viewport [ 1 ] ) ;
assert ( dimensions ( element ) [ 0 ] > 0 && dimensions ( element ) [ 1 ] > 0 ) ;
console . log ( JSON . stringify ( { geometry , full : dimensions ( full ) , card : dimensions ( element ) } ) ) ;
} ) ;
这个夹具生成一个全页面PNG和一个区域PNG。该脚本使用生成的缓冲区验证PNG尺寸。它断言960 CSS像素宽,并报告高度和组件大小。默认字体等布局细节可能会改变测量的高度。在声明视觉一致性之前,确认期望的区域在视觉上存在。定位器截图参考 解释了元素捕获行为。
[Screenshot: 已批准的测试报告旁边的全页面和区域捕获,没有账户信息。]
第4步。协调捕获并关闭会话 记录阶段、应用程序构建、捕获范围和几何形状。仅存储所需的图像。该脚本关闭其自己的页面和连接。从仪表板或拥有控制器结束原始受管理会话,然后验证关闭。请参阅 会话生命周期管理 。
为什么重复截图会不同? 重复截图在浏览器几何、内容、时间、字体或渲染环境发生变化时会有所不同。首先确保两个图像显示相同的记录和检查点。如果应用程序在每个请求上更改时间戳或广告位置,则要么使夹具确定性,要么在测试允许时掩盖特定的变化元素。保持真实缺陷周围的区域可见。
症状 可能原因 实际检查 有效PNG中有空白面板 数据或字体准备情况 断言已知内容并等待所需资源 图像尺寸不同 范围、视口、缩放或滚动高度 比较报告的几何和捕获选项 运行间布局移动 不同字体、操作系统、设备比例或内容 在一致且记录的环境中运行 元素图像缺少部分 收缩状态、溢出或虚拟渲染 打开约定状态并使用更狭窄的断言 出现不想要的覆盖层 对话框、同意或登录状态 使用批准的夹具状态并明确验证
视觉回归阈值应遵循产品的容忍度。来自不同环境的截图可能会揭示有用的错误,但不应自动替换参考。在同一视口下捕获已知成功,然后重现意图上的失败。Playwright视觉比较指南 。
如何使截图在不同版本之间可比较? 通过将测试条件与基线存储在一起,使发布截图可比较。使用相同的夹具数据、浏览器构建、批准的字体、视口、缩放和捕获范围。将视觉检查保留在命名检查点,而不是捕获每个中间状态。如果报告使用动态日期,请在夹具中设定一个固定日期,并在捕获之前断言它。
对于间歇性视觉故障,仅保存仍包含缺陷的最小图像和一个全页面上下文图像(仅在需要时)。首先比较尺寸。如果文档高度因过滤后的数据集有更多行而变化,则像素差异可能是输入变化的症状。检查渲染的数据计数和预期的夹具,然后再替换参考图像。
Nstdata Cloud Browser 如何支持捕获工作流程? Nstdata Cloud Browser 提供用于浏览器自动化和 AI 代理的托管云浏览器。它允许工作人员连接到正在运行的浏览器,并捕获由其自身经过批准的操作生成的页面状态。配置的代理可以在该客户端中不需要单独的代理配置即可路由区域测试。实时视图帮助操作员确认正在运行的浏览器显示的内容。您的测试仍然决定捕获哪个区域以及保留哪些证据。
CDP 执行。 保留相同的 Playwright 断言,并在远程浏览器内捕获操作。
环境选择。 配置预期的初始屏幕并检查页面中的实际视口。
实时观察。 如果捕获不完整,将图像与实时页面、控制台或网络证据关联。
最终截图旁边应该有什么? 存储一个简短的清单,包括测试用例、批准的源路由、时间戳、视口、DPR、范围、预期标记和测试判决。在将工件发送给授权以外的受众之前,清理捕获的内容。在私有作业元数据中保留托管的会话 ID,以便开发人员可以在相关历史记录过期之前进行故障排除。在集成捕获和关闭时,请咨询 云浏览器自动化指南 。
FAQ Q: 完整页面截图会加载每个懒惰元素吗?
明确验证所需元素。完整页面捕获涵盖文档的渲染范围,这可能包括数据尚未加载的部分。
Q: 为什么图像比配置的屏幕更窄?
检查内容视口和 CSS 缩放。浏览器外观或显式视口覆盖可能会改变页面可用的区域。
Q: 我需要在捕获前使用固定的延迟吗?
更倾向于使用有意义的就绪标记。当这些资产是证据的一部分时,添加特定的字体或资源检查。
Q: 会话回放是否可以替代视觉回归截图?
使用截图比较获取像素证据。归档的 DOM 回放支持序列诊断,可以显示不同的字体或图像。
Q: Playwright 会在云浏览器的文件系统中保存截图吗?
此示例中的截图路径属于 Node.js 调用者。对其工件目录应用访问和保留控制。
Marcus Chen
Nov. 19th 2026
从网页抓取、测试到 AI 驱动的自动化,一切都在云端运行。 探索 Cloud Browser →