Assert API TLS Security Details with Playwright

Playwright API response TLS security details let a test connect an API result to the negotiated TLS protocol, certificate dates, informational issuer and subject names, plus the observed server address. Assert only an owned transport policy, keep certificate verification enabled, handle optional fields deliberately, and pair metadata with status and business-response checks.

These methods add transport evidence to Playwright API testing; they do not turn an API test into a complete certificate audit. Use them for a focused release decision such as "the public health endpoint uses an approved TLS protocol and a currently valid certificate." For mutual TLS, combine server evidence with the verified Playwright client-certificate configuration and an application identity assertion.

Define the TLS Security Decision

Start with the policy owner and the exact endpoint. "Check TLS" is not a release rule. A usable rule identifies the URL, whether redirects are permitted, the allowed negotiated protocol values, the required certificate validity window, and whether an observed network peer must meet an environment-specific constraint.

Keep three layers separate:

• Connection acceptance: the HTTPS request succeeds with certificate verification enabled.
• Reported metadata: Playwright returns protocol, validity timestamps, and optional informational certificate names.
• Application behavior: the response status, content type, schema, and business state match the API contract.

A green metadata assertion cannot rescue a 500 response. A correct JSON body cannot rescue a TLS policy violation. Report them as related but distinct gates so ownership is clear.

Choose the first observable failure boundary. A certificate verification error can prevent any APIResponse from being created. A non-HTTPS endpoint produces a response but securityDetails() resolves to null. An HTTPS endpoint can return complete metadata yet violate the team's allowed protocol set. A proxy may make the observed server address differ from an origin address assumed by the author.

Record whether the test uses a direct endpoint, enterprise proxy, service mesh, or public gateway. The network path determines what the API client actually negotiates. A scoped HAR replay or recording workflow can help correlate redirects and response headers, but HAR evidence should not replace the live TLS connection required by this gate.

Do not invent a universal minimum protocol or expiry threshold in test code. Read approved values from reviewed configuration and fail clearly when the configuration is absent. Policy may differ between a public endpoint, an internal lab service, and a compatibility environment.

Check Version Support and API Semantics

The Playwright release notes add APIResponse.securityDetails() and APIResponse.serverAddr() in version 1.61. The installed 1.61.1 TypeScript definitions expose both as asynchronous methods on the APIResponse returned by APIRequestContext calls.

securityDetails() resolves to null for a non-HTTPS response. Otherwise, its object can include these optional fields:

• protocol, such as the exact string reported for the negotiated TLS version.
• issuer, the common-name component of the certificate issuer, for informational use.
• subjectName, the common-name component of the certificate subject, for informational use.
• validFrom and validTo, Unix timestamps measured in seconds.

serverAddr() resolves to an object with ipAddress and port, or null when unavailable. For a followed redirect chain, both methods report the final request. They do not return a list of every hop.

The fields do not expose the complete certificate chain, subject alternative names, cipher suite, revocation result, or all handshake properties. Do not cast the result to a richer type or infer missing values. A dedicated TLS scanner belongs beside this test when policy needs those facts.

Verify the executable version in CI, especially if editor types come from another workspace. Keep the transport check in a project that pins 1.61 or later. The broader API testing guide covers request contexts, credentials, fixtures, and business assertions that remain necessary around this new metadata.

Build a Typed TLS Policy Assertion

Put policy comparison in a small helper that accepts an APIResponse and reviewed configuration. The helper should reject HTTP, missing required fields, expired or not-yet-valid certificates, and unapproved protocols without logging sensitive response data.

Example 1: Assert negotiated protocol and certificate dates

import { expect, type APIResponse } from '@playwright/test';

type TlsPolicy = {
  allowedProtocols: readonly string[];
  minimumRemainingSeconds: number;
};

export async function expectTlsPolicy(
  response: APIResponse,
  policy: TlsPolicy,
): Promise<void> {
  const details = await response.securityDetails();
  if (!details)
    throw new Error(`Expected HTTPS security details for ${new URL(response.url()).origin}`);

  if (!details.protocol)
    throw new Error('TLS protocol was not reported');
  expect(policy.allowedProtocols).toContain(details.protocol);

  if (details.validFrom === undefined || details.validTo === undefined)
    throw new Error('Certificate validity timestamps were not reported');

  const now = Math.floor(Date.now() / 1_000);
  expect(details.validFrom).toBeLessThanOrEqual(now);
  expect(details.validTo).toBeGreaterThan(
    now + policy.minimumRemainingSeconds,
  );
}

The function treats required optional fields explicitly. Optional in the API type means the runtime may omit them; it does not mean a security policy must silently skip them. If a particular environment cannot provide a required field, mark that gate unsupported with an owned reason rather than passing it.

The URL in the error is reduced to origin. Avoid printing paths and query strings because health and callback endpoints may contain signed values. Do not print certificate values by default; a mismatch message can name the policy field and allowed set.

Use Unix seconds consistently. JavaScript Date.now() returns milliseconds, so divide and floor before comparing. Store the minimum remaining validity as configuration, not a magic number embedded in every spec.

Exercise the Real API Endpoint

Call a low-impact HTTPS endpoint that represents the same gateway and certificate path as the protected API. A health or version endpoint is suitable only if it terminates TLS at the same boundary. Avoid a destructive business operation merely to obtain transport metadata.

Example 2: Combine TLS, address, and API contract checks

import { expect, test } from '@playwright/test';
import { expectTlsPolicy } from './tls-policy';

test('public API meets the release transport policy', async ({ request }) => {
  const endpoint = process.env.PUBLIC_API_HEALTH_URL;
  if (!endpoint) throw new Error('PUBLIC_API_HEALTH_URL is required');

  const response = await request.get(endpoint, { maxRedirects: 0 });

  expect(response.status()).toBe(200);
  expect(response.headers()['content-type']).toContain('application/json');

  await expectTlsPolicy(response, {
    allowedProtocols: ['TLS 1.3'],
    minimumRemainingSeconds: 604_800,
  });

  const address = await response.serverAddr();
  if (!address) throw new Error('Server address was not reported');
  expect(address.port).toBe(443);

  expect(await response.json()).toMatchObject({ status: 'ok' });
  await response.dispose();
});

The values in this example are a sample policy, not a universal recommendation. Replace them with approved configuration for the target system. If the endpoint uses a nonstandard TLS port by design, assert that owned value. If certificate rotation policy requires a different warning window, encode that reviewed threshold centrally.

maxRedirects: 0 prevents a cleartext or cross-origin redirect from disappearing behind final-hop metadata. The expected response status should reflect that choice. In suites that allow redirects, validate each approved hop through a separate direct probe or a lower-level redirect inspection path.

Dispose the response body after use when the request context remains alive. API response bodies stay in memory until disposal or context closure. A single small health body is harmless, but consistent lifecycle ownership prevents a large security suite from retaining unnecessary content.

Feed only a small transport summary into the Playwright evidence pipeline: origin label, negotiated protocol, validity timestamps, address availability, port, policy version, and terminal decision. Do not attach the body merely because the transport test read it.

Assert Policy Without Overstating Certificate Proof

An issuer or subject common name can help explain an unexpected certificate, but Playwright marks those fields as informational. Modern hostname validation relies on certificate rules that cannot be reconstructed from subjectName alone. Keep ordinary HTTPS validation enabled and let connection failure remain a blocker.

Never set ignoreHTTPSErrors: true in the release-gate request context. That option allows the client to proceed despite certificate errors, removing a critical part of the evidence. If a lab test deliberately connects to an expired or self-signed fixture, isolate the context, name the bypass in the test, and prevent its output from satisfying production policy.

For mTLS, a successful HTTPS response plus expected application identity can prove the configured client reached an authorized path. securityDetails() reports server-side certificate information; it does not identify which client certificate the server accepted. Use the client certificate testing guide and server audit evidence when client identity is the decision.

Do not snapshot the full details object. Certificate rotation can change informational names or dates without violating policy, while snapshots make every field appear equally important. Assert the fields tied to a control and attach selected values only when access policy permits them.

Distinguish a validity warning from an expired certificate. A certificate whose validTo is after the current time may still violate an operational renewal window. Report the remaining duration and policy threshold as structured numbers. Avoid invented severity labels unless the organization defines them.

If the endpoint is fronted by a content delivery network or enterprise proxy, the observed certificate may belong to that approved termination layer. Document the expected boundary. A mismatch can indicate a real route change, but it can also reveal that the test was executed through an environment not covered by the policy.

Handle Redirects and Server Addresses Deliberately

Automatic redirects make a convenient API call but narrow what metadata describes. With redirects enabled, Playwright returns final-request TLS details and final server address. A starting HTTP endpoint that redirects to HTTPS can therefore produce valid final metadata while the initial cleartext hop remains outside the object.

Set maxRedirects: 0 when the entry URL itself must be HTTPS and redirect-free. If one redirect is part of the public contract, probe the first endpoint without following it, assert the exact allowed status and safe destination origin, then probe the HTTPS destination separately. Do not log a signed Location value.

Server addresses are diagnostic, not automatically stable assertions. A direct internal service may have an owned IP range. A public gateway may rotate addresses, use IPv6, or resolve differently by region. A corporate proxy can become the observed peer. Decide whether the gate requires exact IP, approved CIDR, port only, or merely address availability.

When network policy depends on address ranges, use a real IP parser and CIDR library already approved by the project. String prefixes do not validate network membership and can mishandle IPv6. Keep the policy data versioned and owned by the network team.

Routing and Service Workers primarily affect browser traffic, while APIRequestContext follows its own client path. Use the route and Service Worker troubleshooting guide when comparing browser and API evidence, and state when the two clients traverse different proxies or gateways.

Design Positive, Negative, and Boundary Cases

Build the matrix from transport controls, not random endpoints. Every negative case should identify whether failure happens before an APIResponse, in returned metadata, or in the application contract.

1. Verify an approved HTTPS endpoint with required protocol and current validity window.
2. Call an HTTP fixture and assert securityDetails() is null rather than treating absence as an exception.
3. Use a controlled redirect fixture to prove final-hop semantics and the no-redirect gate.
4. Exercise a lab certificate that is expired or not yet valid with normal verification and assert request rejection.
5. Test missing optional fields through a typed fixture or adapter unit test, not by weakening the live gate.
6. Run through the approved CI proxy and confirm the expected address policy for that path.
7. Validate an application error response over valid TLS so transport and business failures remain separate.

Use this failure matrix:

Do not use HAR replay for the positive TLS gate. Replayed responses deliberately remove the live connection whose protocol and certificate are under test. HAR can support a UI fallback scenario, but mark that case as mocked.

Compare Available Network Evidence

Use a decision table to prevent one convenient API from being stretched beyond its output.

Browser Response has related security and address methods, but it belongs to page traffic. APIResponse belongs to APIRequestContext. Keep the types and report labels distinct, especially when comparing browser and direct-client paths.

The Playwright WebSocket mocking guide serves message-level edge cases, not an API TLS gate. A secure wss connection still needs a live handshake and protocol-specific assertion. Use each observation at its own transport layer.

External scanners and platform certificate monitors remain valuable for chain, revocation, cipher, and fleet-wide coverage. The Playwright test contributes an application-adjacent check from the CI path and can connect transport policy to the exact API contract used by the suite.

Protect TLS Evidence and Test Credentials

Security metadata is less sensitive than a response body, but it still reveals infrastructure. Internal issuer names, subjects, IP addresses, ports, and origins can help an attacker map services. Publish only what the report audience needs. Keep raw address evidence in restricted artifacts when the public report can use an approved-range decision instead.

Never attach request headers, client keys, certificate PEM data, proxy credentials, or bearer tokens. Configure secrets through the CI secret store and limit the test identity. If a mismatch occurs, report the configuration key name and policy revision, not the secret value.

The official Tracing API can preserve browser chronology, but a direct API TLS gate usually needs only a structured summary. If the surrounding browser flow is traced, scan it independently because traces can contain network headers and bodies unrelated to the TLS assertion.

Use the AI-generated test evidence checklist when reviewing helpers. Reject code that enables ignoreHTTPSErrors, logs entire response objects, hard-codes private addresses, or silently skips missing fields. Every skip must name the unsupported environment and an owner.

Rotate any credential accidentally published in a report. Deleting the artifact is not enough once external storage or notifications may have copied it. Record the incident without preserving the exposed value and review every related evidence channel.

Debug Missing or Misleading TLS Details

Classify failures before changing policy. Start with URL scheme, redirect behavior, request-context options, and the actual network path.

Capture a sanitized failure marker before adding more logging. Origin, test project, proxy class, Playwright version, redirect setting, and whether a response object exists usually narrow the problem. Add selected metadata only after confirming it can be retained.

Use Playwright CLI trace analysis when a browser flow and API probe disagree. Compare target origin, proxy configuration, client certificates, and redirect path. The clients may legitimately terminate at different boundaries.

Do not auto-update expected issuer names or network ranges from the failing environment. Those values are security policy inputs and require owner review. A generated baseline from a compromised or misrouted endpoint would convert the defect into the expectation.

Add a Deterministic CI Gate

Run the TLS gate from the network path whose compliance matters. Pin Playwright, define the endpoint and policy through reviewed configuration, and keep automatic retries off for certificate failures. A retry can confirm a transient address issue, but it must not erase the first transport result.

Example 3: Attach a selected, body-free TLS summary

const details = await response.securityDetails();
const address = await response.serverAddr();

await test.info().attach('tls-policy-summary.json', {
  body: Buffer.from(JSON.stringify({
    endpoint: new URL(response.url()).origin,
    protocol: details?.protocol ?? null,
    validFrom: details?.validFrom ?? null,
    validTo: details?.validTo ?? null,
    addressAvailable: address !== null,
    port: address?.port ?? null,
    policyVersion: process.env.TLS_POLICY_VERSION ?? 'missing',
  })),
  contentType: 'application/json',
});

Apply these gate rules:

1. Block when normal HTTPS validation prevents a required endpoint from returning a response.
2. Block when the negotiated protocol or validity interval violates reviewed policy.
3. Block when a required metadata field is unavailable; report unsupported environments separately from passes.
4. Block unexpected redirects before evaluating final-hop details.
5. Apply address rules appropriate to the known proxy, gateway, and deployment topology.
6. Block product release independently when status, schema, or business assertions fail over valid TLS.
7. Reject evidence that contains credentials, private key material, full headers, or unapproved infrastructure detail.

Run a fast endpoint gate on relevant deployment changes and a broader matrix on gateway, proxy, certificate, or Playwright upgrades. Feed the selected summary into the Playwright evidence pipeline and retain it according to the security classification, not merely test status.

Frequently Asked Questions

What does APIResponse.securityDetails() return?

It resolves to security information for an HTTPS API response, including optional issuer, protocol, subjectName, validFrom, and validTo fields. It resolves to null for non-HTTPS responses. For redirects that Playwright follows, the details describe the final request in the chain rather than every TLS connection.

Can securityDetails() prove hostname validation?

Not by comparing subjectName alone. Playwright labels issuer and subject common-name values as informational, and the method does not expose the complete certificate chain or subject alternative names. Keep HTTPS validation enabled, test the intended hostname, and use a certificate-aware scanner when the release policy requires deeper certificate proof.

Why does serverAddr() return null?

The address can be unavailable for the response or environment, in which case serverAddr() resolves to null. Treat availability as an explicit test prerequisite before requiring an IP assertion. Also account for proxies, service meshes, load balancers, and address rotation, because the observed peer may not be a fixed application origin.

Which redirect does APIResponse TLS metadata describe?

When redirects are followed, both securityDetails() and serverAddr() describe the final request in the redirect chain. They do not provide a complete per-hop TLS audit. Set maxRedirects to zero or probe each approved HTTPS origin directly when every redirect boundary must satisfy an independently asserted policy.

Should a TLS test use ignoreHTTPSErrors?

No for a release security gate. Enabling ignoreHTTPSErrors permits certificate errors that the gate is meant to catch, so a successful request would provide false confidence. A separate negative fixture may use it only to inspect a deliberately invalid lab endpoint, with the bypass clearly isolated and excluded from release evidence.

Is a fixed server IP a good CI assertion?

Usually not for services behind elastic infrastructure. Assert an approved network class, port, or environment-specific range only when that boundary is stable and owned. Record the observed address as restricted diagnostic metadata when useful, but do not turn routine load-balancer rotation or IPv4-to-IPv6 changes into product regressions.

Practice a Transport-Aware Release Decision

Choose one read-only HTTPS endpoint and write its transport policy before implementation. Add the API response check with redirects disabled, assert the approved protocol and validity window, then classify address evidence for the actual CI topology. Add HTTP, redirect, and invalid-certificate fixtures so every missing response or metadata field has a named meaning.

Take that gate into QABattle's automation battles and defend each assertion: which fact Playwright exposes, which deeper certificate claim needs another tool, and why application health remains independent. The finished test should reject an unsafe connection without publishing secrets or turning normal infrastructure rotation into noise.