Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat(fetch): expose securityDetails() and serverAddr() on APIResponse (#40932)

Dmitry Gozmanb949df5b6d2a
diff --git a/docs/src/api/class-apiresponse.md b/docs/src/api/class-apiresponse.md
index bbc70f5df4..48ca44eb8a 100644
--- a/docs/src/api/class-apiresponse.md
+++ b/docs/src/api/class-apiresponse.md
@@ -90,6 +90,16 @@ This method will throw if the response body is not parsable via `JSON.parse`.
Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
+## async method: APIResponse.securityDetails = %%-response-security-details-%%
+* since: v1.61
+
+Returns SSL and other security information. Resolves to `null` for non-HTTPS responses. For redirected requests, returns the information for the last request in the redirect chain.
+
+## async method: APIResponse.serverAddr = %%-response-server-addr-%%
+* since: v1.61
+
+Returns the IP address and port of the server. Resolves to `null` if the server address is not available. For redirected requests, returns the information for the last request in the redirect chain.
+
## method: APIResponse.status
* since: v1.16
- returns: <[int]>
diff --git a/docs/src/api/class-response.md b/docs/src/api/class-response.md
index 6584ee3417..555d2210c0 100644
--- a/docs/src/api/class-response.md
+++ b/docs/src/api/class-response.md
@@ -118,30 +118,13 @@ Contains a boolean stating whether the response was successful (status in the ra
Returns the matching [Request] object.
-## async method: Response.securityDetails
+## async method: Response.securityDetails = %%-response-security-details-%%
* since: v1.13
-- returns: <[null]|[Object]>
- * alias: SecurityDetails
- * alias-csharp: ResponseSecurityDetailsResult
- - `issuer` ?<[string]> Common Name component of the Issuer field.
- from the certificate. This should only be used for informational purposes. Optional.
- - `protocol` ?<[string]> The specific TLS protocol used. (e.g. `TLS 1.3`). Optional.
- - `subjectName` ?<[string]> Common Name component of the Subject
- field from the certificate. This should only be used for informational purposes. Optional.
- - `validFrom` ?<[float]> Unix timestamp (in seconds) specifying
- when this cert becomes valid. Optional.
- - `validTo` ?<[float]> Unix timestamp (in seconds) specifying
- when this cert becomes invalid. Optional.
Returns SSL and other security information.
-## async method: Response.serverAddr
+## async method: Response.serverAddr = %%-response-server-addr-%%
* since: v1.13
-- returns: <[null]|[Object]>
- * alias-csharp: ResponseServerAddrResult
- * alias-java: ServerAddr
- - `ipAddress` <[string]> IPv4 or IPV6 address of the server.
- - `port` <[int]>
Returns the IP address and port of the server.
diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index 491395efd7..d64bfc7957 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -1986,3 +1986,24 @@ In this config:
- `timeout` ?<[int]> How long to wait for the process to start up and be available in milliseconds. Defaults to 60000.
- `url` ?<[string]> The url on your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the server is ready to accept connections. Redirects (3xx status codes) are being followed and the new location is checked. Either `port` or `url` should be specified.
+## response-security-details
+- returns: <[null]|[Object]>
+ * alias: SecurityDetails
+ * alias-csharp: ResponseSecurityDetailsResult
+ - `issuer` ?<[string]> Common Name component of the Issuer field.
+ from the certificate. This should only be used for informational purposes. Optional.
+ - `protocol` ?<[string]> The specific TLS protocol used. (e.g. `TLS 1.3`). Optional.
+ - `subjectName` ?<[string]> Common Name component of the Subject
+ field from the certificate. This should only be used for informational purposes. Optional.
+ - `validFrom` ?<[float]> Unix timestamp (in seconds) specifying
+ when this cert becomes valid. Optional.
+ - `validTo` ?<[float]> Unix timestamp (in seconds) specifying
+ when this cert becomes invalid. Optional.
+
+## response-server-addr
+- returns: <[null]|[Object]>
+ * alias-csharp: ResponseServerAddrResult
+ * alias-java: ServerAddr
+ - `ipAddress` <[string]> IPv4 or IPV6 address of the server.
+ - `port` <[int]>
+
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index 05fe4dc968..7bae445814 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -18828,6 +18828,52 @@ export interface APIResponse {
*/
ok(): boolean;
+ /**
+ * Returns SSL and other security information. Resolves to `null` for non-HTTPS responses. For redirected requests,
+ * returns the information for the last request in the redirect chain.
+ */
+ securityDetails(): Promise<null|{
+ /**
+ * Common Name component of the Issuer field. from the certificate. This should only be used for informational
+ * purposes. Optional.
+ */
+ issuer?: string;
+
+ /**
+ * The specific TLS protocol used. (e.g. `TLS 1.3`). Optional.
+ */
+ protocol?: string;
+
+ /**
+ * Common Name component of the Subject field from the certificate. This should only be used for informational
+ * purposes. Optional.
+ */
+ subjectName?: string;
+
+ /**
+ * Unix timestamp (in seconds) specifying when this cert becomes valid. Optional.
+ */
+ validFrom?: number;
+
+ /**
+ * Unix timestamp (in seconds) specifying when this cert becomes invalid. Optional.
+ */
+ validTo?: number;
+ }>;
+
+ /**
+ * Returns the IP address and port of the server. Resolves to `null` if the server address is not available. For
+ * redirected requests, returns the information for the last request in the redirect chain.
+ */
+ serverAddr(): Promise<null|{
+ /**
+ * IPv4 or IPV6 address of the server.
+ */
+ ipAddress: string;
+
+ port: number;
+ }>;
+
/**
* Contains the status code of the response (e.g., 200 for a success).
*/
diff --git a/packages/playwright-core/src/client/fetch.ts b/packages/playwright-core/src/client/fetch.ts
index 95f2e94084..8d58a81f0f 100644
--- a/packages/playwright-core/src/client/fetch.ts
+++ b/packages/playwright-core/src/client/fetch.ts
@@ -26,7 +26,7 @@ import { mkdirIfNeeded } from './fileUtils';
import { TimeoutSettings } from './timeoutSettings';
import type { Playwright } from './playwright';
-import type { ClientCertificate, FilePayload, Headers, SetStorageState, StorageState, TimeoutOptions } from './types';
+import type { ClientCertificate, FilePayload, Headers, RemoteAddr, SecurityDetails, SetStorageState, StorageState, TimeoutOptions } from './types';
import type { Serializable } from '../../types/structs';
import type * as api from '../../types/types';
import type { HeadersArray, NameValue } from '@isomorphic/types';
@@ -340,6 +340,14 @@ export class APIResponse implements api.APIResponse {
return this._headers.headersArray();
}
+ async securityDetails(): Promise<SecurityDetails | null> {
+ return this._initializer.securityDetails ?? null;
+ }
+
+ async serverAddr(): Promise<RemoteAddr | null> {
+ return this._initializer.serverAddr ?? null;
+ }
+
async body(): Promise<Buffer> {
return await this._request._wrapApiCall(async () => {
try {
diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts
index a89255ed20..af1c8ecc2b 100644
--- a/packages/playwright-core/src/protocol/validator.ts
+++ b/packages/playwright-core/src/protocol/validator.ts
@@ -359,6 +359,8 @@ scheme.APIResponse = tObject({
status: tInt,
statusText: tString,
headers: tArray(tType('NameValue')),
+ securityDetails: tOptional(tType('SecurityDetails')),
+ serverAddr: tOptional(tType('RemoteAddr')),
});
scheme.ArtifactInitializer = tObject({
absolutePath: tString,
diff --git a/packages/playwright-core/src/server/fetch.ts b/packages/playwright-core/src/server/fetch.ts
index b392e18d49..7299449c04 100644
--- a/packages/playwright-core/src/server/fetch.ts
+++ b/packages/playwright-core/src/server/fetch.ts
@@ -496,6 +496,8 @@ export abstract class APIRequestContext extends SdkObject {
status: response.statusCode || 0,
statusText: response.statusMessage || '',
headers: toHeadersArray(response.rawHeaders),
+ securityDetails,
+ serverAddr: serverIPAddress !== undefined && serverPort !== undefined ? { ipAddress: serverIPAddress, port: serverPort } : undefined,
},
});
};
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 05fe4dc968..7bae445814 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -18828,6 +18828,52 @@ export interface APIResponse {
*/
ok(): boolean;
+ /**
+ * Returns SSL and other security information. Resolves to `null` for non-HTTPS responses. For redirected requests,
+ * returns the information for the last request in the redirect chain.
+ */
+ securityDetails(): Promise<null|{
+ /**
+ * Common Name component of the Issuer field. from the certificate. This should only be used for informational
+ * purposes. Optional.
+ */
+ issuer?: string;
+
+ /**
+ * The specific TLS protocol used. (e.g. `TLS 1.3`). Optional.
+ */
+ protocol?: string;
+
+ /**
+ * Common Name component of the Subject field from the certificate. This should only be used for informational
+ * purposes. Optional.
+ */
+ subjectName?: string;
+
+ /**
+ * Unix timestamp (in seconds) specifying when this cert becomes valid. Optional.
+ */
+ validFrom?: number;
+
+ /**
+ * Unix timestamp (in seconds) specifying when this cert becomes invalid. Optional.
+ */
+ validTo?: number;
+ }>;
+
+ /**
+ * Returns the IP address and port of the server. Resolves to `null` if the server address is not available. For
+ * redirected requests, returns the information for the last request in the redirect chain.
+ */
+ serverAddr(): Promise<null|{
+ /**
+ * IPv4 or IPV6 address of the server.
+ */
+ ipAddress: string;
+
+ port: number;
+ }>;
+
/**
* Contains the status code of the response (e.g., 200 for a success).
*/
diff --git a/packages/protocol/spec/api.yml b/packages/protocol/spec/api.yml
index 9f293a20c4..c92ad1b99f 100644
--- a/packages/protocol/spec/api.yml
+++ b/packages/protocol/spec/api.yml
@@ -100,3 +100,5 @@ APIResponse:
headers:
type: array
items: NameValue
+ securityDetails: SecurityDetails?
+ serverAddr: RemoteAddr?
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index 4990815165..c2f9cea282 100644
--- a/packages/protocol/src/channels.d.ts
+++ b/packages/protocol/src/channels.d.ts
@@ -738,6 +738,8 @@ export type APIResponse = {
status: number,
statusText: string,
headers: NameValue[],
+ securityDetails?: SecurityDetails,
+ serverAddr?: RemoteAddr,
};
// ----------- Artifact -----------
diff --git a/tests/library/global-fetch.spec.ts b/tests/library/global-fetch.spec.ts
index 402f6d7368..bb8100c483 100644
--- a/tests/library/global-fetch.spec.ts
+++ b/tests/library/global-fetch.spec.ts
@@ -234,6 +234,29 @@ it('should propagate ignoreHTTPSErrors on redirects', async ({ playwright, https
await request.dispose();
});
+it('should return server address from response', async ({ playwright, server }) => {
+ const request = await playwright.request.newContext();
+ const response = await request.get(server.EMPTY_PAGE);
+ const addr = await response.serverAddr();
+ expect(addr!.ipAddress).toMatch(/^(127\.0\.0\.1|::1)$/);
+ expect(addr!.port).toBe(server.PORT);
+ await request.dispose();
+});
+
+it('should return security details from response', async ({ playwright, httpsServer }) => {
+ const request = await playwright.request.newContext({ ignoreHTTPSErrors: true });
+ const response = await request.get(httpsServer.EMPTY_PAGE);
+ expect(await response.securityDetails()).toEqual({ issuer: 'playwright-test', protocol: 'TLSv1.3', subjectName: 'playwright-test', validFrom: 1691708270, validTo: 2007068270 });
+ await request.dispose();
+});
+
+it('should return null security details for http response', async ({ playwright, server }) => {
+ const request = await playwright.request.newContext();
+ const response = await request.get(server.EMPTY_PAGE);
+ expect(await response.securityDetails()).toBeNull();
+ await request.dispose();
+});
+
it('should resolve url relative to global baseURL option', async ({ playwright, server }) => {
const request = await playwright.request.newContext({ baseURL: server.PREFIX });
const response = await request.get('/empty.html');