Cypress trustedCertificates enables disk caching for declared certificate origins

Introduced 2026-09-15 · score 0.93

HOW TO USE IT

When running asset-heavy specs on Chrome, Chromium, or Edge with an untrusted application certificate, add that certificate or its SPKI fingerprint to `trustedCertificates`. Cypress then lets the browser trust the declared origin so its static assets can be cached across navigations.

const { defineConfig } = require('cypress')
module.exports = defineConfig({
  trustedCertificates: [{ filePath: '<project-relative-path-to-PEM-certificate>' }],
})

const { defineConfig } = require('cypress')
module.exports = defineConfig({
  trustedCertificates: [{ pem: '<inline-PEM-certificate-text>' }],
})

const { defineConfig } = require('cypress')
module.exports = defineConfig({
  trustedCertificates: [{ spki: '<44-character-base64-SHA-256-SPKI-fingerprint-ending-in-equals>' }],
})

WHY THIS HELPS

Run asset-heavy specs against an application presenting an untrusted development certificate on Chrome, Chromium, or Edge.

BEFORE THIS CHANGE

Before this change, responses from an untrusted-certificate origin were not written to the browser disk cache, so asset-heavy specs re-downloaded assets on each `cy.visit()`.

REQUIREMENTS AND LIMITATIONS

Version: 16.1.0
trustedCertificates: Optional array of certificate entries; defaults to `[]`.
trustedCertificates[].filePath: Path to a PEM-encoded certificate file; relative paths resolve against the project root. Exactly one entry key must be used.
trustedCertificates[].pem: Inline PEM-encoded certificate text. Every certificate in the PEM string is trusted. Exactly one entry key must be used.
trustedCertificates[].spki: Precomputed base64-encoded SHA-256 fingerprint of the certificate SPKI; exactly 44 characters ending in `=`. Exactly one entry key must be used.
filePath, pem, spki exclusivity (required): Each entry must contain exactly one of these keys; using zero or multiple keys causes configuration validation error. They are mutually exclusive.
Prerequisite: Cypress 16.1.0 or later; the option was added in 16.1.0.
Prerequisite: Applies on the native browser network path in Chrome, Chromium, and Edge. It has no effect in Firefox, WebKit, Electron, or when `forceHttp1: true`.
Prerequisite: A `filePath` entry must be readable and PEM data must parse; those failures occur at browser launch. Validation checks entry shape first.
Applies on the native browser network path in Chrome, Chromium, and Edge.
Origins not declared continue to load as before.
Firefox, WebKit, Electron, and `forceHttp1` runs are unaffected.

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card

Tools change faster than your agent’s training data.

Changes

Cypress trustedCertificates enables disk caching for declared certificate origins