Playwright Java API 测试详解用 RequestOptions 构建 HTTP 请求【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright本篇技术文章围绕 Playwright 文档中的 RequestOptions 类展开它是 Java API 中构造 APIRequestContext 请求参数的唯一入口用于设置请求方法、请求体JSON / 表单 / multipart 文件上传、请求头、查询参数、超时、重定向与重试等选项。读完本文你将掌握 RequestOptions 全部 11 个方法的用途与取值规则、内容类型Content-Type的自动推断逻辑并能结合 packages/playwright-core/src/client/fetch.ts 中的底层实现理解选项如何被校验和序列化。RequestOptions 的定位Java 版本的请求选项对象RequestOptions自 v1.18 引入文档中明确标注langs: java即它是Java API 特有的选项对象。在 Java 中APIRequestContext的get/post/put/patch/head/delete/fetch方法都接受一个可选的RequestOptions参数// RequestOptions 与 APIRequestContext 配合的典型用法 context.request().post( https://example.com/submit, RequestOptions.create() .setQueryParam(page, 1) .setData(My data));从源码结构看这种设计是跨语言 API 对齐的产物。在 参数文档 中可以看到各语言 fetch 选项的定义JavaScript 使用对象字面量params、headers、data、form、multipart等命名字段js-fetch-option-params 等条目而 Java 的 java-fetch-params 条目定义为一整包可选的options RequestOptions对象即把同一组选项收敛到一个可链式调用的构建器Builder里。文档原文说明其核心目的RequestOptions用于创建要经由APIRequestContext发送的表单数据且Playwright 会自动确定请求的内容类型。构造实例create 与链式调用method: RequestOptions.createRequestOptions options RequestOptions.create();create是静态工厂方法返回新的RequestOptions实例。文档中所有set*方法签名均声明returns: RequestOptions因此支持链式调用最终把构建完成的实例整体传给请求方法// 配合通用的 fetch 方法使用 APIResponse response context.request().fetch(https://example.com/api/createBook, RequestOptions.create() .setMethod(post) .setData(data)); // data 为 MapString, Object将自动 JSON 序列化RequestOptions既可传给fetch通用方法也可直接传给post/get等便捷方法——后者已隐含 HTTP 方法无需再调用setMethod。请求体三选一setData / setForm / setMultipartPlaywright 提供三种互斥的请求体设置方式对应不同Content-Type。这一互斥约束并非仅停留在文档层面JS 客户端实现 packages/playwright-core/src/client/fetch.ts 中有显式断言Only one of data, form or multipart can be specified即一次请求中这三种参数最多只能指定一个Java 的RequestOptions通过同一个协议层发送请求遵循同样的规则。setData原始数据 / JSON 对象data参数类型为string | Buffer | SerializableJava 中Serializable即 Java 对象如Map。内容类型推断规则为若 data 是对象非字符串、非字节数组序列化为 JSON 字符串且未显式设置时Content-Type为application/json否则字符串 / 字节未显式设置时Content-Type为application/octet-stream。底层实现印证了这条规则fetch.ts 的_innerFetch中字符串 data 会先判断请求头是否为 JSON 内容类型可解析则按 JSON 处理否则按 UTF-8 字节缓冲发送对象/数字/布尔类型直接JSON.stringify。// 发送 JSON 请求体 MapString, Object data new HashMap(); data.put(title, Book Title); data.put(body, John Doe); request.post(https://example.com/api/createBook, RequestOptions.create().setData(data)); // 发送原始字符串 context.request().post( https://example.com/submit, RequestOptions.create() .setQueryParam(page, 1) .setData(My data));setFormapplication/x-www-form-urlencoded 表单setForm接收 FormData 对象将其序列化为 HTML 表单并以application/x-www-form-urlencoded编码作为请求体指定后若未显式提供Content-Type头将自动设置为该值// 上传 HTML 表单数据 context.request().post(https://example.com/signup, RequestOptions.create().setForm( FormData.create() .set(firstName, John) .set(lastName, Doe)));setMultipartmultipart/form-data 与文件上传setMultipart同样接收FormData但使用multipart/form-data编码发送这是以表单字段形式上传文件的常规方式。文件字段有两种给法直接传java.nio.file.Path或手动构造FilePayload包含文件名、MIME 类型与字节内容// 方式一直接传文件路径 Path path Paths.get(members.csv); APIResponse response context.request().post(https://example.com/upload_members, RequestOptions.create().setMultipart(FormData.create().set(membersList, path))); // 方式二手动构造文件载荷无需落盘的文件 FilePayload filePayload new FilePayload(members.csv, text/csv, Alice, 33\nJohn, 35\n.getBytes(StandardCharsets.UTF_8)); APIResponse response context.request().post(https://example.com/upload_members, RequestOptions.create().setMultipart(FormData.create().set(membersList, filePayload)));三种请求体方式汇总如下方法内容类型默认典型场景setData对象 →application/json其他 →application/octet-streamREST API 的 JSON 提交、原始字节setFormapplication/x-www-form-urlencoded经典 HTML 表单提交setMultipartmultipart/form-data带文件上传的表单请求头、查询参数与方法setHeader设置单个 HTTP 请求头。文档特别强调该头会同时作用于请求本身及其引发的所有重定向——这对跨重定向保持Authorization等头的场景很关键。参数为name string与value string。RequestOptions options RequestOptions.create() .setHeader(Authorization, Bearer token) .setHeader(Accept, application/vnd.github.v3json);setQueryParam向请求 URL 追加查询参数参数值支持string | boolean | int可多次调用以叠加多个参数request.get(https://example.com/api/getText, RequestOptions.create() .setQueryParam(isbn, 1234) .setQueryParam(page, 23));对应到 JS/Python这些选项等价于params对象或字符串见 params.md 中js-fetch-option-params等定义。setMethod切换 HTTP 方法如PUT、POST仅在调用通用的fetch方法时需要使用post、put等便捷方法时方法已固定。request.fetch(https://example.com/api/createBook, RequestOptions.create().setMethod(post).setData(data));可靠性选项超时、失败判定、HTTPS、重定向与重试方法参数类型默认值说明setTimeoutfloat毫秒3000030 秒请求超时传0禁用超时setFailOnStatusCodebooleanfalse响应码非 2xx/3xx 时抛异常默认对所有状态码都返回响应对象setIgnoreHTTPSErrorsbooleanfalse忽略请求的 HTTPS 证书错误setMaxRedirectsv1.26int20自动跟随的重定向上限超出抛错传0不跟随重定向setMaxRetriesv1.46int0网络错误最大重试次数当前仅重试ECONNRESET不基于 HTTP 状态码重试使用示例APIResponse response context.request().get(https://example.com/slow, RequestOptions.create() .setTimeout(60_000) // 放宽到 60 秒 .setFailOnStatusCode(true) // 非 2xx/3xx 直接抛错 .setMaxRedirects(0)); // 不跟随重定向直接检查 3xx实现层面这些约束同样在协议边界被强校验fetch.ts 对maxRedirects与maxRetries均断言必须 0。从源码结构看Java 侧的RequestOptions经由packages/protocol/定义的协议字段PlaywrightFetchRequest中的maxRedirects、maxRetries等见 packages/playwright-core/src/client/channels.d.ts传递到服务端的 fetch 执行器因此上述默认值与校验行为在各语言间保持一致。与其他语言 API 的对照RequestOptions的每个方法都对应其他语言 fetch 选项中的一个命名字段迁移或对照查阅时可参考 APIRequestContext 文档 的多语言示例JavaRequestOptions方法JS / Python / C# 选项名setDatadatasetFormformsetMultipartmultipartsetHeaderheaders对象形式setQueryParamparamssetMethodmethodsetTimeouttimeoutsetFailOnStatusCodefailOnStatusCodesetIgnoreHTTPSErrorsignoreHTTPSErrorssetMaxRedirectsmaxRedirectssetMaxRetriesmaxRetriesJava 语言层面的完整用法鉴权、文件上传、断言可进一步参阅 Java API 测试指南。测试验证与延伸阅读仓库中的测试套件覆盖了APIRequestContext的上述行为可作为选项实际效果的验证依据tests/library/global-fetch.spec.ts独立请求上下文playwright.request.newContext()下的请求行为tests/library/browsercontext-fetch.spec.ts与浏览器上下文共享 Cookie 的请求上下文行为tests/library/browsercontext-fetch-algorithms.spec.ts请求算法细节。配套文档还包括 FormData 类setForm/setMultipart的载体、APIRequest 上下文创建与 Cookie 共享机制以及参数定义源文件 params.md。需要注意的适用前提本文所述方法版本标注v1.18 / v1.26 / v1.46以当前仓库文档为准使用旧版本 Playwright 时请以所用版本自带的 API 文档核对setMaxRedirects、setMaxRetries是否可用。【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考