From e2b587024f48b7481f1c932df192ca9dec4d891c Mon Sep 17 00:00:00 2001 From: Alin Voinea Date: Fri, 18 Sep 2026 18:44:16 +0300 Subject: [PATCH] skill: add volto-cypress-writer --- CHANGELOG.md | 14 ++ catalog.yaml | 18 ++ skills/volto-cypress-writer/SKILL.md | 197 ++++++++++++++++++ .../volto-cypress-writer/EEA-OVERRIDES.md | 35 ++++ src/skills/volto-cypress-writer/SKILL.md | 152 ++++++++++++++ src/skills/volto-cypress-writer/metadata.json | 18 ++ 6 files changed, 434 insertions(+) create mode 100644 skills/volto-cypress-writer/SKILL.md create mode 100644 src/skills/volto-cypress-writer/EEA-OVERRIDES.md create mode 100644 src/skills/volto-cypress-writer/SKILL.md create mode 100644 src/skills/volto-cypress-writer/metadata.json diff --git a/CHANGELOG.md b/CHANGELOG.md index c2cad62..ea5534c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,20 @@ This project uses **date-based versioning** (YYYY-MM-DD) rather than semantic ve --- +## 2026-09-18 — Add Volto Cypress Writer Skill + +### Added +- New `volto-cypress-writer` skill (`src/skills/volto-cypress-writer/`): + - `SKILL.md` with a generic Plone/Volto Cypress workflow that discovers the project `specPattern`, helper layout, and commands + - `EEA-OVERRIDES.md` with EEA-wide Cypress policy (Volto version matrix, CI targets, local reproduction) + - `metadata.json` with skill index data +- `catalog.yaml` entry for `volto-cypress-writer` + +### Why +The skill previously hardcoded the `eea-website` layout (`frontend/src/addons`, `cypress/e2e`). It is now generic across EEA Volto generations, which use different spec directories (`cypress/e2e` vs `cypress/tests`), add-on locations, and test runners. + +--- + ## 2026-08-07 — Fix PR #1 Review Findings and Refocus the Testing Skill ### Fixed diff --git a/catalog.yaml b/catalog.yaml index f2bdd0c..d3da376 100644 --- a/catalog.yaml +++ b/catalog.yaml @@ -212,6 +212,24 @@ skills: added_date: "2026-07-29" notes: EEA-original skill covering the dev/Jenkins test-command parity contract and, going forward, guidance for closing real coverage gaps with meaningful tests rather than ones that only move the number. + - id: volto-cypress-writer + name: Volto Cypress Writer + description: Cypress E2E writing and maintenance for Plone/Volto add-ons and projects in EEA, including UI-first setup, selectors, helpers, flake reduction, and Cypress commands. + category: frontend + upstream: null + triggers: + - cypress + - e2e + - acceptance test + - volto + - add-on + - selector + - flaky test + version: "1.0.0" + eeaspecific: true + added_date: "2026-09-18" + notes: EEA-original skill covering Cypress for Plone/Volto add-ons and projects; discovers the project specPattern and commands instead of hardcoding them. + # Future skills placeholder # - chart: Data visualization and chart generation # - doc: Technical documentation generation diff --git a/skills/volto-cypress-writer/SKILL.md b/skills/volto-cypress-writer/SKILL.md new file mode 100644 index 0000000..bbcbd11 --- /dev/null +++ b/skills/volto-cypress-writer/SKILL.md @@ -0,0 +1,197 @@ +--- +name: volto-cypress-writer +description: > + Cypress E2E writing and maintenance for Plone/Volto add-ons and projects in + EEA. Use when writing, updating, reviewing, or debugging Cypress tests, + including UI-first setup, stable selectors, helpers, flake reduction, and + add-on/project Cypress commands. +license: MIT +metadata: + author: EEA + version: "1.0.0" + eeaspecific: "true" +--- + +# Volto Cypress Writer + +Use this skill when writing, updating, reviewing, or debugging Cypress tests for +EEA Plone/Volto add-ons and projects. + +## Discover the project first + +EEA Volto codebases come from more than one template generation, and their +Cypress setup differs. Before editing, read: + +- `cypress.config.js` — the `specPattern`, `baseUrl`, reporter, and setup events +- `Makefile` — run `make help` for the real Cypress targets +- `cypress/support/e2e.js` and `cypress/support/commands.js` — the helper layout +- nearby specs — the existing naming and helper style + +Put new specs where the project's `specPattern` points, not in a hardcoded +directory. Common layouts are `cypress/e2e/**/*.cy.js` (legacy add-ons) and +`cypress/tests/**/*.cy.{js,jsx,ts,tsx}` (Cookieplone projects/add-ons). + +Put reusable feature helpers in `cypress/support/.js` unless the project +already uses a different convention. Keep global Cypress commands minimal; +prefer imported helpers for feature-specific flows. + +## UI-First Rule + +New tests must set up state, navigate, edit, save, and assert through the browser UI. + +- Do not add or call `cy.request()` setup helpers for new tests unless the user explicitly asks for legacy/API-seeded style. +- Existing REST helpers such as `autologin`, `createContent`, and `removeContent` may be read for context, but do not copy them into new UI-first flows. +- Use the UI for the behavior under test even when an older suite uses API shortcuts. +- If UI-only setup is impractical for a narrow reason, stop and explain the constraint before changing the approach. + +## Selectors + +- Prefer stable `data-cy` or `data-testid` selectors. +- If stable selectors are missing and component edits are in scope, add explicit test selectors to the component instead of relying on DOM shape. +- Use role, label, placeholder, or visible text when they describe the user's intent. +- Avoid positional selectors like `:nth-child()` and style-driven selectors like `.ui.basic.icon.button...`. +- If Volto or Semantic UI markup forces a fragile selector, hide it behind a named helper such as `openBlockChooser()` or `saveCurrentPage()`. +- Keep assertions user-visible where possible: URL, heading, block text, saved view output, modal state, toolbar state, validation message. + +## Reliability + +- Each spec must pass independently; do not depend on previous tests. +- Use `beforeEach` for browser state and content setup. +- Prefer Cypress retry-ability: `cy.get(...).should(...)`, `cy.contains(...).should(...)`, and URL assertions. +- Prefer `cy.intercept().as()` and `cy.wait('@alias')` for network-dependent transitions. +- Avoid arbitrary `cy.wait(ms)`. If a Volto editor limitation requires one, keep it local and add a short comment explaining why. +- Avoid per-command `{ timeout: ... }`; wait for observable UI or network state instead. If a timeout override is unavoidable, keep it local and document the reason. +- Split chains after actions before assertions: + +```js +cy.get('[data-cy="toolbar-save"]').click(); +cy.get('[data-cy="view-page"]').should('be.visible'); +``` + +- Avoid `{ force: true }` unless Volto overlays or hidden controls make it unavoidable; explain the reason in a helper or nearby comment. +- Do not suppress uncaught exceptions broadly unless the test target is a known third-party integration and the user accepts that tradeoff. + +## Volto Add-on Patterns + +- The add-on Cypress config usually sets `baseUrl: 'http://localhost:3000'` and passes Plone API settings through `CYPRESS_API_PATH`, `RAZZLE_DEV_PROXY_API_PATH`, or `RAZZLE_INTERNAL_API_PATH`. +- Add-on tests normally live beside the add-on, not in the root project `cypress/` directory. +- Cypress tests for an add-on must pass against every Volto version the add-on supports (commonly 17, 18, and 19) unless the user explicitly scopes the task to one version. Read the versions from the project and template generation. +- For block tests, cover the edit flow and the saved view: + - create or navigate to a page through the UI + - add the block through the block chooser + - configure the fields through the sidebar or inline editor + - save + - assert the view mode output +- For editor interactions, prefer existing Slate helpers if the add-on already has them. Add focused helpers only when they reduce repeated low-level selection/type logic. + +## Commands + +Run add-on Cypress commands from the add-on directory when the add-on has its own +Makefile. Start by checking the available targets: + +```sh +make help +``` + +Common flows (names vary by generation; use what `make help` reports): + +```sh +make install +make start +make cypress-run +make cypress-open +``` + +Non-default Volto version (legacy and Cookieplone add-ons): + +```sh +VOLTO_VERSION=18-yarn make install +VOLTO_VERSION=18-yarn make start +make cypress-run +``` + +`VOLTO_VERSION` selects the add-on environment during install/start; it does not +change Cypress itself. Run Cypress against the Volto version that is currently +started. + +Cookieplone projects expose project-level targets: + +```sh +make cypress +make cypress-open +``` + +Run one spec: + +```sh +npx cypress run --spec "" +``` + +Useful debugging and CI-style targets (confirm they exist in the target +`Makefile` before using them): + +```sh +make shell +make check-ci +make cypress-ci +``` + +Use the smallest relevant command for verification. For a Cypress-only change, +prefer the target's Cypress command in every supported Volto environment. + +## Review Checklist + +- The test exercises the feature like a user, not by mutating backend state. +- Selectors are stable or wrapped in named helpers. +- The test asserts both edit-time behavior and saved output when relevant. +- The suite can run test cases independently. +- The Cypress behavior works in every supported Volto version, or the version-specific limitation is clearly reported. +- Network or async transitions wait on observable conditions, not fixed sleeps. +- Per-command `{ timeout: ... }` overrides are avoided or explicitly justified. +- Helpers are local to the add-on/project unless multiple specs need them. +- The command used to verify is reported back to the user. + +--- + + +# EEA-Specific Overrides + + + +## EEA Cypress policy + +### Version matrix + +Cypress suites in EEA Volto add-ons must pass against every Volto version the +add-on supports (commonly 17, 18, and 19). Read the supported versions from the +project and template generation; run the suite against each unless the task is +explicitly scoped to one version. + +### CI targets + +EEA add-ons expose CI-oriented targets, typically: + +- `make check-ci` — wait for the frontend to be ready. +- `make cypress-ci` — run headless in the CI browser. +- `make cypress-run` — run headless locally. + +The EEA Jenkins pipeline publishes JUnit results from `cypress/reports/*.xml` +and coverage from `@cypress/code-coverage`. Do not change the reporter without +updating the pipeline expectation. + +### Local reproduction + +Run the same target Jenkins runs (`make cypress-ci` when available) so local and +CI results match. Start the backend/frontend the way the add-on does +(`make install` / `make start`, with `VOLTO_VERSION=...` for a non-default Volto). + +## Handoff to other EEA skills + +- General frontend work → `plone-frontend-developer` +- CI and quality gates → `jenkins-pipeline`, `code-quality`, `testing` + + + + + + diff --git a/src/skills/volto-cypress-writer/EEA-OVERRIDES.md b/src/skills/volto-cypress-writer/EEA-OVERRIDES.md new file mode 100644 index 0000000..6f02d92 --- /dev/null +++ b/src/skills/volto-cypress-writer/EEA-OVERRIDES.md @@ -0,0 +1,35 @@ +# EEA-Specific Overrides + + + +## EEA Cypress policy + +### Version matrix + +Cypress suites in EEA Volto add-ons must pass against every Volto version the +add-on supports (commonly 17, 18, and 19). Read the supported versions from the +project and template generation; run the suite against each unless the task is +explicitly scoped to one version. + +### CI targets + +EEA add-ons expose CI-oriented targets, typically: + +- `make check-ci` — wait for the frontend to be ready. +- `make cypress-ci` — run headless in the CI browser. +- `make cypress-run` — run headless locally. + +The EEA Jenkins pipeline publishes JUnit results from `cypress/reports/*.xml` +and coverage from `@cypress/code-coverage`. Do not change the reporter without +updating the pipeline expectation. + +### Local reproduction + +Run the same target Jenkins runs (`make cypress-ci` when available) so local and +CI results match. Start the backend/frontend the way the add-on does +(`make install` / `make start`, with `VOLTO_VERSION=...` for a non-default Volto). + +## Handoff to other EEA skills + +- General frontend work → `plone-frontend-developer` +- CI and quality gates → `jenkins-pipeline`, `code-quality`, `testing` diff --git a/src/skills/volto-cypress-writer/SKILL.md b/src/skills/volto-cypress-writer/SKILL.md new file mode 100644 index 0000000..d50bf77 --- /dev/null +++ b/src/skills/volto-cypress-writer/SKILL.md @@ -0,0 +1,152 @@ +--- +name: volto-cypress-writer +description: > + Cypress E2E writing and maintenance for Plone/Volto add-ons and projects in + EEA. Use when writing, updating, reviewing, or debugging Cypress tests, + including UI-first setup, stable selectors, helpers, flake reduction, and + add-on/project Cypress commands. +license: MIT +metadata: + author: EEA + version: "1.0.0" + eeaspecific: "true" +--- + +# Volto Cypress Writer + +Use this skill when writing, updating, reviewing, or debugging Cypress tests for +EEA Plone/Volto add-ons and projects. + +## Discover the project first + +EEA Volto codebases come from more than one template generation, and their +Cypress setup differs. Before editing, read: + +- `cypress.config.js` — the `specPattern`, `baseUrl`, reporter, and setup events +- `Makefile` — run `make help` for the real Cypress targets +- `cypress/support/e2e.js` and `cypress/support/commands.js` — the helper layout +- nearby specs — the existing naming and helper style + +Put new specs where the project's `specPattern` points, not in a hardcoded +directory. Common layouts are `cypress/e2e/**/*.cy.js` (legacy add-ons) and +`cypress/tests/**/*.cy.{js,jsx,ts,tsx}` (Cookieplone projects/add-ons). + +Put reusable feature helpers in `cypress/support/.js` unless the project +already uses a different convention. Keep global Cypress commands minimal; +prefer imported helpers for feature-specific flows. + +## UI-First Rule + +New tests must set up state, navigate, edit, save, and assert through the browser UI. + +- Do not add or call `cy.request()` setup helpers for new tests unless the user explicitly asks for legacy/API-seeded style. +- Existing REST helpers such as `autologin`, `createContent`, and `removeContent` may be read for context, but do not copy them into new UI-first flows. +- Use the UI for the behavior under test even when an older suite uses API shortcuts. +- If UI-only setup is impractical for a narrow reason, stop and explain the constraint before changing the approach. + +## Selectors + +- Prefer stable `data-cy` or `data-testid` selectors. +- If stable selectors are missing and component edits are in scope, add explicit test selectors to the component instead of relying on DOM shape. +- Use role, label, placeholder, or visible text when they describe the user's intent. +- Avoid positional selectors like `:nth-child()` and style-driven selectors like `.ui.basic.icon.button...`. +- If Volto or Semantic UI markup forces a fragile selector, hide it behind a named helper such as `openBlockChooser()` or `saveCurrentPage()`. +- Keep assertions user-visible where possible: URL, heading, block text, saved view output, modal state, toolbar state, validation message. + +## Reliability + +- Each spec must pass independently; do not depend on previous tests. +- Use `beforeEach` for browser state and content setup. +- Prefer Cypress retry-ability: `cy.get(...).should(...)`, `cy.contains(...).should(...)`, and URL assertions. +- Prefer `cy.intercept().as()` and `cy.wait('@alias')` for network-dependent transitions. +- Avoid arbitrary `cy.wait(ms)`. If a Volto editor limitation requires one, keep it local and add a short comment explaining why. +- Avoid per-command `{ timeout: ... }`; wait for observable UI or network state instead. If a timeout override is unavoidable, keep it local and document the reason. +- Split chains after actions before assertions: + +```js +cy.get('[data-cy="toolbar-save"]').click(); +cy.get('[data-cy="view-page"]').should('be.visible'); +``` + +- Avoid `{ force: true }` unless Volto overlays or hidden controls make it unavoidable; explain the reason in a helper or nearby comment. +- Do not suppress uncaught exceptions broadly unless the test target is a known third-party integration and the user accepts that tradeoff. + +## Volto Add-on Patterns + +- The add-on Cypress config usually sets `baseUrl: 'http://localhost:3000'` and passes Plone API settings through `CYPRESS_API_PATH`, `RAZZLE_DEV_PROXY_API_PATH`, or `RAZZLE_INTERNAL_API_PATH`. +- Add-on tests normally live beside the add-on, not in the root project `cypress/` directory. +- Cypress tests for an add-on must pass against every Volto version the add-on supports (commonly 17, 18, and 19) unless the user explicitly scopes the task to one version. Read the versions from the project and template generation. +- For block tests, cover the edit flow and the saved view: + - create or navigate to a page through the UI + - add the block through the block chooser + - configure the fields through the sidebar or inline editor + - save + - assert the view mode output +- For editor interactions, prefer existing Slate helpers if the add-on already has them. Add focused helpers only when they reduce repeated low-level selection/type logic. + +## Commands + +Run add-on Cypress commands from the add-on directory when the add-on has its own +Makefile. Start by checking the available targets: + +```sh +make help +``` + +Common flows (names vary by generation; use what `make help` reports): + +```sh +make install +make start +make cypress-run +make cypress-open +``` + +Non-default Volto version (legacy and Cookieplone add-ons): + +```sh +VOLTO_VERSION=18-yarn make install +VOLTO_VERSION=18-yarn make start +make cypress-run +``` + +`VOLTO_VERSION` selects the add-on environment during install/start; it does not +change Cypress itself. Run Cypress against the Volto version that is currently +started. + +Cookieplone projects expose project-level targets: + +```sh +make cypress +make cypress-open +``` + +Run one spec: + +```sh +npx cypress run --spec "" +``` + +Useful debugging and CI-style targets (confirm they exist in the target +`Makefile` before using them): + +```sh +make shell +make check-ci +make cypress-ci +``` + +Use the smallest relevant command for verification. For a Cypress-only change, +prefer the target's Cypress command in every supported Volto environment. + +## Review Checklist + +- The test exercises the feature like a user, not by mutating backend state. +- Selectors are stable or wrapped in named helpers. +- The test asserts both edit-time behavior and saved output when relevant. +- The suite can run test cases independently. +- The Cypress behavior works in every supported Volto version, or the version-specific limitation is clearly reported. +- Network or async transitions wait on observable conditions, not fixed sleeps. +- Per-command `{ timeout: ... }` overrides are avoided or explicitly justified. +- Helpers are local to the add-on/project unless multiple specs need them. +- The command used to verify is reported back to the user. diff --git a/src/skills/volto-cypress-writer/metadata.json b/src/skills/volto-cypress-writer/metadata.json new file mode 100644 index 0000000..b4b656f --- /dev/null +++ b/src/skills/volto-cypress-writer/metadata.json @@ -0,0 +1,18 @@ +{ + "id": "volto-cypress-writer", + "name": "Volto Cypress Writer", + "description": "Cypress E2E writing and maintenance for Plone/Volto add-ons and projects in EEA, including UI-first setup, selectors, helpers, flake reduction, and Cypress commands.", + "version": "1.0.0", + "eeaspecific": true, + "upstream": null, + "added_date": "2026-09-18", + "triggers": [ + "cypress", + "e2e", + "acceptance test", + "volto", + "add-on", + "selector", + "flaky test" + ] +}