diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index 28ed11a86f..f301a5f880 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -523,14 +523,14 @@ Does not enforce fixed viewport, allows resizing window in the headed mode.
     - `pfxPath` ?<[string]> Path to the PFX or PKCS12 encoded private key and certificate chain.
     - `passphrase` ?<[string]> Passphrase for the private key (PEM or PFX).
 
-An array of client certificates to be used. Each certificate object must have `cert` and `key` or `pfx` to load the client certificate. Optionally, `passphrase` property should be provided if the private key is encrypted. If the certificate is valid only for specific URLs, the `url` property should be provided with a glob pattern to match the URLs that the certificate is valid for.
+An array of client certificates to be used. Each certificate object must have both `certPath` and `keyPath` or a single `pfxPath` to load the client certificate. Optionally, `passphrase` property should be provided if the private key is encrypted. If the certificate is valid only for specific URLs, the `url` property should be provided with a glob pattern to match the URLs that the certificate is valid for.
 
 :::note
 Using Client Certificates in combination with Proxy Servers is not supported.
 :::
 
 :::note
-When using WebKit on macOS, accessing `localhost` might not work as expected.
+When using WebKit on macOS, accessing `localhost` will not pick up client certificates. You can make it work by replacing `localhost` with `local.playwright`.
 Instead, use `playwright.local` as the hostname.
 :::
 
diff --git a/tests/assets/client-certificates/README.md b/tests/assets/client-certificates/README.md
index bba37cbb48..499a41e115 100644
--- a/tests/assets/client-certificates/README.md
+++ b/tests/assets/client-certificates/README.md
@@ -49,7 +49,7 @@ openssl req \
 	-days 365 \
 	-subj "/CN=Bob"
 
-# sign with bob_csr.pem
+# sign with self-signed/key.pem
 openssl x509 \
 	-req \
 	-in client/self-signed/csr.pem \