Skip to content

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

docs: Add client certificates activation and rejection behavior documentation (#36793)

Copilot9b0f042cdaba
diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index d8278abd6a..8cb60f038f 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -563,6 +563,8 @@ TLS Client Authentication allows the server to request a client certificate and
An array of client certificates to be used. Each certificate object must have either both `certPath` and `keyPath`, a single `pfxPath`, or their corresponding direct value equivalents (`cert` and `key`, or `pfx`). Optionally, `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided with an exact match to the request origin that the certificate is valid for.
+Client certificate authentication is only active when at least one client certificate is provided. If you want to reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that does not match any of the domains you plan to visit.
+
:::note
When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it work by replacing `localhost` with `local.playwright`.
:::
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index e840adc980..63a2a2d9c9 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -9738,6 +9738,10 @@ export interface Browser {
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
+ * Client certificate authentication is only active when at least one client certificate is provided. If you want to
+ * reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
+ * does not match any of the domains you plan to visit.
+ *
* **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it
* work by replacing `localhost` with `local.playwright`.
*
@@ -14821,6 +14825,10 @@ export interface BrowserType<Unused = {}> {
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
+ * Client certificate authentication is only active when at least one client certificate is provided. If you want to
+ * reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
+ * does not match any of the domains you plan to visit.
+ *
* **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it
* work by replacing `localhost` with `local.playwright`.
*
@@ -17534,6 +17542,10 @@ export interface APIRequest {
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
+ * Client certificate authentication is only active when at least one client certificate is provided. If you want to
+ * reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
+ * does not match any of the domains you plan to visit.
+ *
* **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it
* work by replacing `localhost` with `local.playwright`.
*
@@ -22068,6 +22080,10 @@ export interface BrowserContextOptions {
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
+ * Client certificate authentication is only active when at least one client certificate is provided. If you want to
+ * reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
+ * does not match any of the domains you plan to visit.
+ *
* **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it
* work by replacing `localhost` with `local.playwright`.
*
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index e840adc980..63a2a2d9c9 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -9738,6 +9738,10 @@ export interface Browser {
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
+ * Client certificate authentication is only active when at least one client certificate is provided. If you want to
+ * reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
+ * does not match any of the domains you plan to visit.
+ *
* **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it
* work by replacing `localhost` with `local.playwright`.
*
@@ -14821,6 +14825,10 @@ export interface BrowserType<Unused = {}> {
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
+ * Client certificate authentication is only active when at least one client certificate is provided. If you want to
+ * reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
+ * does not match any of the domains you plan to visit.
+ *
* **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it
* work by replacing `localhost` with `local.playwright`.
*
@@ -17534,6 +17542,10 @@ export interface APIRequest {
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
+ * Client certificate authentication is only active when at least one client certificate is provided. If you want to
+ * reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
+ * does not match any of the domains you plan to visit.
+ *
* **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it
* work by replacing `localhost` with `local.playwright`.
*
@@ -22068,6 +22080,10 @@ export interface BrowserContextOptions {
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
+ * Client certificate authentication is only active when at least one client certificate is provided. If you want to
+ * reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
+ * does not match any of the domains you plan to visit.
+ *
* **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it
* work by replacing `localhost` with `local.playwright`.
*
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 45916cef63..13e31cd833 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -6982,6 +6982,10 @@ export interface PlaywrightTestOptions {
* `passphrase` property should be provided if the certificate is encrypted. The `origin` property should be provided
* with an exact match to the request origin that the certificate is valid for.
*
+ * Client certificate authentication is only active when at least one client certificate is provided. If you want to
+ * reject all client certificates sent by the server, you need to provide a client certificate with an `origin` that
+ * does not match any of the domains you plan to visit.
+ *
* **NOTE** When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it
* work by replacing `localhost` with `local.playwright`.
*