influxdata / influxdata/docs-v2

chore(ci): upgrade Cypress 14.5.4 → 15.x

Open
#7,067 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:ci
Dominant language
JavaScript
Stars
82
Forks
326
Avg merge
1d 1h
Merged PRs (30d)
82

Description

## Summary

Cypress is one major version behind. The repo currently installs `cypress@14.5.4` (pinned as `^14.0.1` in `package.json`); latest is `15.13.0` (released 2026-03-24). This issue tracks the upgrade and documents the breaking-change exposure found in our test suite and CI.

## Current state

- `package.json` devDependency: `cypress: ^14.0.1`
- Installed: `14.5.4`
- `engines.node`: `>=16.0.0` (stale — Node 16 is EOL, Node 18 also EOL)
- No component testing (e2e only)
- No `@cypress/webpack-preprocessor`, `@cypress/vite-dev-server`, or `SelectorPlayground` API usage

## Breaking changes in 15.0.0 relevant to this repo

### 1. `cy.exec()` result field renamed `code` → `exitCode`

**Impact:** 4 occurrences, all in warning-only branches. Tests won't fail, but warning logs will fire on every run because `undefined !== 0` is always true.

- `cypress/e2e/content/llm-format-selector.cy.js:28`
- `cypress/e2e/content/llm-format-selector.cy.js:44`
- `cypress/e2e/content/markdown-content-validation.cy.js:40`
- `cypress/e2e/content/markdown-content-validation.cy.js:56`

**Fix:** rename `result.code` → `result.exitCode` in all four places.

### 2. Node.js 18 and 23 support dropped

Cypress 15 requires Node `^20.1.0 || ^22.0.0 || >=24.0.0`.

**Does not directly block the upgrade** — the workflows that install and run Cypress already use Node 20:

- `.github/actions/setup-docs-env/action.yml` → Node 20
- `.github/workflows/pr-preview.yml` → Node 20
- `.github/workflows/pr-link-check.yml` → Node 20

But `package.json` `engines.node: ">=16.0.0"` is now a lie and should be bumped to `>=20.1.0`.

Unrelated Node 18 workflow cleanup (`audit-documentation.yml`, `prepare-release.yml`, `influxdb3-release.yml`) is tracked separately.

### 3. `cy.url()`, `cy.hash()`, `cy.go()`, `cy.reload()`, `cy.title()`, `cy.location()` now use CDP / WebDriver BiDi

These commands now read values through the browser automation client instead of the `window` object. Behavior is the same for same-origin tests but cross-origin handling changed.

**Impact:** used in 6 spec files (`page-context.cy.js`, `topnav.cy.js`, `index.cy.js`, `tc-downloads.cy.js`, `api-reference.cy.js`, `markdown-content-validation.cy.js`). All uses are same-origin against `localhost:1315`. No code changes expected, but smoke-test after the bump.

### 4. Not affected

- No `cy.stub(obj, name, fn)` 3-arg signature usage
- No `Cypress.SelectorPlayground` / `getSelector` usage
- No component testing → webpack / vite / Angular CT breaks don't apply
- `CYPRESS_INSTALL_BINARY=0` + `yarn install` flow still works (direct download removal only affects manual downloads)

## Non-breaking but noteworthy: `Cypress.env()` deprecated in 15.10.0

**The repo doesn't use `Cypress.env()` anywhere in test code**, so this is not a migration blocker.

While investigating I confirmed that the test-subjects plumbing in `cypress/support/run-e2e-specs.js` and `cypress.config.js` is dead code:

- `env: { test_subjects, test_subjects_data, skipExternalLinks }` set in `run-e2e-specs.js:401-408` — no reader
- `env: { test_subjects: '' }` set in `cypress.config.js:202` — no reader
- `/tmp/test_subjects.txt` written at `run-e2e-specs.js:242` — no reader
- `/tmp/test_subjects_sources.json` written at `run-e2e-specs.js:246,253` — no reader

No spec, plugin, or support file reads any of it. Something was refactored and the plumbing was left behind. Not in scope for this issue, but worth cleaning up separately.

### Future migration path (if we start using `Cypress.env()`)

- New command: `cy.env('KEY')` — async, chainable
- New public API: `Cypress.expose()` — for non-sensitive values
- New config: `allowCypressEnv: false` — hard-disables the deprecated API
- `Cypress.env()` remains functional through all 15.x; removal in a future major

See: https://docs.cypress.io/app/references/migration-guide#Migrating-away-from-Cypressenv

## Proposed upgrade steps

1. Bump `devDependencies.cypress` to `^15.13.0` in `package.json`
2. Bump `engines.node` to `>=20.1.0`
3. Rename `result.code` → `result.exitCode` (4 occurrences listed above)
4. `yarn install` and regenerate `yarn.lock`
5. Run full suite locally: `node cypress/support/run-e2e-specs.js --spec "cypress/e2e/**/*.cy.js" --no-mapping`
6. Run the markdown-validation specs specifically to confirm the `cy.exec` warning branches behave correctly
7. Verify pr-preview and pr-link-check workflows pass in CI

## References

- Cypress 15.0.0 release notes: https://docs.cypress.io/app/references/changelog#15-0-0
- Cypress 15 migration guide: https://docs.cypress.io/app/references/migration-guide#Migrating-to-Cypress-150
- Latest (15.13.0) changelog: https://docs.cypress.io/app/references/changelog#15-13-0

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with package.json, the four listed Cypress specs, and the Node 20 workflows; compare the Cypress migration guide with the documented command usage. Run yarn install, the full cypress/support/run-e2e-specs.js command, and the markdown-validation specs. Done means the lockfile and dependency metadata are updated, warning branches behave correctly, and pr-preview and pr-link-check pass in CI.

Written by the indexing model from the issue text.

Assessment

Tech stack
cypress, javascript, node.js
Domain
ci-cd, testing-qa
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.