@jahia/agentic 0.2.0 → 0.3.0

package/dist/gemini/.agents/skills/jahia-dev-cypress/SKILL.md

@@ -1,25 +1,24 @@
 ---
 name: jahia-dev-cypress
-description: Write and scaffold Cypress e2e tests for a Jahia JS template set. Covers directory setup, cypress.config.ts, @jahia/cypress commands, site creation/teardown, content seeding via addNode, component rendering assertions, CSS Module class selectors, and the three mandatory spec files per component.
+description: Write and scaffold Cypress e2e tests for a Jahia JS template set. Covers test-package structure, site seeding, isolation, content setup, rendering assertions, and stable selector strategy.
 ---
 
-# SKILL — Jahia Cypress E2E Tests
+# Skill: jahia-dev-cypress
 
-## When this skill applies
-
-A new component, content type, or page template has been built in a JS template set and needs Cypress coverage. Per the CTO guidelines, tests ship alongside the component — not retroactively.
+Use this skill when a Jahia JS template set needs Cypress end-to-end coverage.
+Tests should ship with the component or page template, not weeks later.
 
 ---
 
 ## Test directory layout
 
-Tests live in a **separate `tests/` directory** at the module root — never inside `src/`.
+Tests live in a separate `tests/` directory at the module root.
 
 ```
 <module>/
-├── src/                         ← component code
+├── src/
 ├── settings/
-├── tests/                       ← Cypress project (separate package)
+├── tests/
 │   ├── package.json
 │   ├── cypress.config.ts
 │   ├── .env.example
@@ -32,42 +31,41 @@ Tests live in a **separate `tests/` directory** at the module root — never ins
 │   │   ├── fixtures/
 │   │   │   └── graphql/
 │   │   │       └── mutation/
-│   │   │           └── *.graphql
 │   │   ├── plugins/
 │   │   │   └── index.js
 │   │   └── support/
 │   │       ├── commands.ts
-│   │       └── constants.ts
+│   │       ├── constants.ts
+│   │       └── e2e.ts
 │   └── results/
-│       └── .gitignore
 └── package.json
 ```
 
 ---
 
-## Step 1 — Scaffold the test package
+## Step 1 — Scaffold the Cypress package
 
 Create `tests/package.json`:
 
 ```json
 {
-    "name": "<module-name>-cypress",
-    "private": true,
-    "scripts": {
-        "e2e:ci": "cypress run",
-        "e2e:debug": "cypress open"
-    },
-    "devDependencies": {
-        "@jahia/cypress": "^7.1.0",
-        "cypress": "^14.0.0",
-        "cypress-terminal-report": "^5.3.12",
-        "typescript": "^5.0.0"
-    },
-    "packageManager": "yarn@4.12.0"
+  "name": "<module-name>-cypress",
+  "private": true,
+  "scripts": {
+    "e2e:ci": "cypress run",
+    "e2e:debug": "cypress open"
+  },
+  "devDependencies": {
+    "@jahia/cypress": "^7.1.0",
+    "cypress": "^14.0.0",
+    "cypress-terminal-report": "^5.3.12",
+    "typescript": "^5.0.0"
+  },
+  "packageManager": "yarn@4.12.0"
 }
 ```
 
-Install:
+Install with:
 
 ```bash
 cd tests && yarn install
@@ -75,371 +73,193 @@ cd tests && yarn install
 
 ---
 
-## Step 2 — cypress.config.ts
+## Step 2 — Configure Cypress
 
 ```typescript
-// tests/cypress.config.ts
-import { defineConfig } from 'cypress'
-import * as fs from 'node:fs'
+import { defineConfig } from 'cypress';
+import * as fs from 'node:fs';
 
 export default defineConfig({
-    chromeWebSecurity: false,
-    defaultCommandTimeout: 10000,
-    requestTimeout: 300000,   // 5 min — site provisioning is slow
-    responseTimeout: 300000,
-    viewportWidth: 1366,
-    viewportHeight: 768,
-    watchForFileChanges: false,
-    screenshotsFolder: './results/screenshots',
-    videosFolder: './results/videos',
-    e2e: {
-        baseUrl: 'http://localhost:8080',
-        specPattern: ['**/**.cy.ts'],
-        setupNodeEvents(on, config) {
-            require('@jahia/cypress/dist/plugins/registerPlugins').registerPlugins(on, config)
-            require('cypress-terminal-report/src/installLogsPrinter')(on, {
-                printLogsToConsole: 'onFail',
-                outputRoot: config.projectRoot + '/results/',
-            })
-            on('task', {
-                readFileMaybe(filename) {
-                    if (fs.existsSync(filename)) return fs.readFileSync(filename, 'utf8')
-                    return null
-                },
-            })
-            return config
+  chromeWebSecurity: false,
+  defaultCommandTimeout: 10000,
+  requestTimeout: 300000,
+  responseTimeout: 300000,
+  viewportWidth: 1366,
+  viewportHeight: 768,
+  watchForFileChanges: false,
+  screenshotsFolder: './results/screenshots',
+  videosFolder: './results/videos',
+  e2e: {
+    baseUrl: 'http://localhost:8080',
+    specPattern: ['**/**.cy.ts'],
+    setupNodeEvents(on, config) {
+      require('@jahia/cypress/dist/plugins/registerPlugins').registerPlugins(on, config);
+      require('cypress-terminal-report/src/installLogsPrinter')(on, {
+        printLogsToConsole: 'onFail',
+        outputRoot: config.projectRoot + '/results/',
+      });
+      on('task', {
+        readFileMaybe(filename) {
+          if (fs.existsSync(filename)) return fs.readFileSync(filename, 'utf8');
+          return null;
         },
+      });
+      return config;
     },
-})
+  },
+});
 ```
 
 ---
 
-## Step 3 — constants.ts
+## Step 3 — Keep tests isolated
+
+### Site-per-suite isolation
+
+Every suite should create its own site in `before()` and delete it in `after()`.
+Do not rely on pre-existing sites.
 
 ```typescript
-// tests/cypress/support/constants.ts
-export const SITE_KEY = '<module-name>-tests'
-export const TEMPLATE_SET = '<module-name>'   // matches module name in package.json
+import { createSite, deleteSite } from '@jahia/cypress';
+
+describe('Hero banner', () => {
+  const SITE_KEY = 'hero-banner-tests';
+
+  before(() => {
+    cy.login();
+    createSite(SITE_KEY, {
+      templateSet: 'my-module',
+      locale: 'en',
+      languages: 'en,fr',
+      serverName: 'localhost',
+    });
+    cy.logout();
+  });
+
+  after(() => {
+    cy.login();
+    deleteSite(SITE_KEY);
+    cy.logout();
+  });
+});
 ```
 
+### Session hygiene
+
+Use `beforeEach` / `afterEach` for login boundaries when the scenario needs authentication.
+
 ---
 
-## Step 4 — The three mandatory spec files
+## Step 4 — Keep the three mandatory spec files
 
-Every component ships exactly these three files. Adapt to the component under test.
+Every component test folder should contain:
 
-### `happy-path.cy.ts` — component renders correctly with valid content
+- `happy-path.cy.ts`
+- `authorization.cy.ts`
+- `edge-cases.cy.ts`
 
-```typescript
-import { addNode, createSite, deleteSite, publishAndWaitJobEnding } from '@jahia/cypress'
-import { SITE_KEY, TEMPLATE_SET } from '../../support/constants'
-
-describe('<ComponentName> — happy path', () => {
-    before(() => {
-        cy.login()
-        createSite(SITE_KEY, {
-            templateSet: TEMPLATE_SET,
-            locale: 'en',
-            languages: 'en,fr',
-            serverName: 'localhost',
-        })
-
-        // Seed a page with a test component
-        addNode({
-            parentPathOrId: `/sites/${SITE_KEY}/home`,
-            name: 'testPage',
-            primaryNodeType: 'jnt:page',
-            properties: [
-                { name: 'jcr:title', value: 'Test Page', language: 'en' },
-                { name: 'j:templateName', value: 'simple' },
-            ],
-        }).then(() => {
-            addNode({
-                parentPathOrId: `/sites/${SITE_KEY}/home/testPage/pagecontent`,
-                name: 'myComponent',
-                primaryNodeType: 'ns:myComponentType',
-                properties: [
-                    { name: 'title', value: 'Hello World', language: 'en' },
-                    { name: 'subtitle', value: 'A subtitle', language: 'en' },
-                ],
-            })
-        })
-
-        publishAndWaitJobEnding(`/sites/${SITE_KEY}`, ['en', 'fr'])
-        cy.logout()
-    })
-
-    after(() => {
-        cy.login()
-        deleteSite(SITE_KEY)
-        cy.logout()
-    })
-
-    beforeEach(() => cy.login())
-    afterEach(() => cy.logout())
-
-    it('renders the component in live mode', () => {
-        cy.visit(`/sites/${SITE_KEY}/home/testPage.html`)
-        cy.get('[data-testid="my-component"]').should('be.visible')
-        cy.contains('Hello World')
-    })
-
-    it('renders the component in FR locale', () => {
-        cy.visit(`/fr/sites/${SITE_KEY}/home/testPage.html`)
-        cy.get('[data-testid="my-component"]').should('be.visible')
-    })
-
-    it('renders the component in preview mode', () => {
-        cy.visit(`/cms/render/default/en/sites/${SITE_KEY}/home/testPage.html`)
-        cy.get('[data-testid="my-component"]').should('be.visible')
-    })
-})
-```
+### Happy path
 
-### `authorization.cy.ts` — access control
+Validate the component renders correctly in live, preview, and at least one secondary locale.
 
-```typescript
-import { addNode, createSite, deleteSite, publishAndWaitJobEnding } from '@jahia/cypress'
-import { SITE_KEY, TEMPLATE_SET } from '../../support/constants'
-
-describe('<ComponentName> — authorization', () => {
-    before(() => {
-        cy.login()
-        createSite(SITE_KEY, {
-            templateSet: TEMPLATE_SET,
-            locale: 'en',
-            serverName: 'localhost',
-        })
-        publishAndWaitJobEnding(`/sites/${SITE_KEY}`, ['en'])
-        cy.logout()
-    })
-
-    after(() => {
-        cy.login()
-        deleteSite(SITE_KEY)
-        cy.logout()
-    })
-
-    it('live page is publicly accessible without login', () => {
-        // No cy.login() — verify anonymous access
-        cy.visit(`/sites/${SITE_KEY}/home.html`)
-        cy.get('body').should('be.visible')
-        // Should NOT redirect to login
-        cy.url().should('not.include', '/login')
-    })
-
-    it('default workspace requires authentication', () => {
-        cy.visit(`/cms/render/default/en/sites/${SITE_KEY}/home.html`)
-        // Unauthenticated → redirected to login or 401
-        cy.url().should('satisfy', (url: string) =>
-            url.includes('/login') || url.includes('/logout')
-        )
-    })
-
-    it('admin can access jcontent for the site', () => {
-        cy.login()
-        cy.visit(`/jahia/jcontent/${SITE_KEY}/en/pages`)
-        cy.get('body').should('be.visible')
-        cy.url().should('not.include', '/login')
-        cy.logout()
-    })
-})
-```
+### Authorization
 
-### `edge-cases.cy.ts` — empty values, missing optional fields, boundary conditions
+Validate anonymous versus authenticated access where relevant.
 
-```typescript
-import { addNode, createSite, deleteSite, publishAndWaitJobEnding } from '@jahia/cypress'
-import { SITE_KEY, TEMPLATE_SET } from '../../support/constants'
-
-describe('<ComponentName> — edge cases', () => {
-    before(() => {
-        cy.login()
-        createSite(SITE_KEY, {
-            templateSet: TEMPLATE_SET,
-            locale: 'en',
-            serverName: 'localhost',
-        })
-
-        // Seed a component with only mandatory fields — all optionals missing
-        addNode({
-            parentPathOrId: `/sites/${SITE_KEY}/home`,
-            name: 'testPage',
-            primaryNodeType: 'jnt:page',
-            properties: [
-                { name: 'jcr:title', value: 'Edge Case Page', language: 'en' },
-                { name: 'j:templateName', value: 'simple' },
-            ],
-        }).then(() => {
-            addNode({
-                parentPathOrId: `/sites/${SITE_KEY}/home/testPage/pagecontent`,
-                name: 'emptyComponent',
-                primaryNodeType: 'ns:myComponentType',
-                // Only mandatory properties — no optional ones
-                properties: [
-                    { name: 'title', value: 'Minimal', language: 'en' },
-                ],
-            })
-        })
-
-        publishAndWaitJobEnding(`/sites/${SITE_KEY}`, ['en'])
-        cy.logout()
-    })
-
-    after(() => {
-        cy.login()
-        deleteSite(SITE_KEY)
-        cy.logout()
-    })
-
-    it('renders without errors when optional fields are empty', () => {
-        cy.visit(`/sites/${SITE_KEY}/home/testPage.html`)
-        // No JS errors
-        cy.on('uncaught:exception', () => false) // log but don't fail on known framework noise
-        cy.get('[data-testid="my-component"]').should('exist')
-        // Optional subtitle should not render a broken element
-        cy.get('[data-testid="subtitle"]').should('not.exist')
-    })
-
-    it('page does not return 500 for any seeded content', () => {
-        cy.request(`/sites/${SITE_KEY}/home/testPage.html`).its('status').should('eq', 200)
-    })
-})
-```
+### Edge cases
+
+Seed only mandatory fields and verify missing optional values do not cause broken renders or 500s.
 
 ---
 
-## Step 5 — Seeding content via GraphQL (alternative to `addNode`)
-
-For complex mutations (adding mixins, setting weakreference properties, bulk batches), use `.graphql` fixture files:
-
-```graphql
-# tests/cypress/fixtures/graphql/mutation/seedMyComponent.graphql
-mutation seedMyComponent($parentPath: String!, $imageUuid: String!) {
-    jcr {
-        mutateNode(pathOrId: $parentPath) {
-            addChild(
-                name: "myComponent"
-                primaryNodeType: "ns:myComponentType"
-                properties: [
-                    { name: "title", value: "Test Title", language: "en" }
-                    { name: "image", type: WEAKREFERENCE, value: $imageUuid }
-                ]
-            ) { uuid }
-        }
-    }
-}
+## Step 5 — Seed content predictably
+
+Use `createSite`, `addNode`, and `publishAndWaitJobEnding` from `@jahia/cypress`.
+
+```typescript
+import { addNode, createSite, deleteSite, publishAndWaitJobEnding } from '@jahia/cypress';
+
+addNode({
+  parentPathOrId: `/sites/${SITE_KEY}/home/testPage/pagecontent`,
+  name: 'myComponent',
+  primaryNodeType: 'ns:myComponentType',
+  properties: [
+    { name: 'title', value: 'Hello World', language: 'en' },
+  ],
+});
+
+publishAndWaitJobEnding(`/sites/${SITE_KEY}`, ['en']);
 ```
 
-Call from a test:
+Prefer fixture files over long inline GraphQL strings when seeding becomes complex.
 
 ```typescript
 cy.apollo({
-    mutationFile: 'graphql/mutation/seedMyComponent.graphql',
-    variables: { parentPath: `/sites/${SITE_KEY}/home/testPage/pagecontent`, imageUuid },
-})
+  mutationFile: 'graphql/mutation/seedMyComponent.graphql',
+  variables: { parentPath: `/sites/${SITE_KEY}/home/testPage/pagecontent` },
+});
 ```
 
 ---
 
-## Step 6 — Targeting CSS Module classes
+## Step 6 — Use stable selectors
 
-CSS Modules hash class names at build time. Never target `.myClass` directly — use the `[class*=]` attribute selector to match the unhashed portion:
+CSS Modules hash class names, so do not target final generated class names directly.
 
 ```typescript
-// ❌ Fragile — class name is hashed
-cy.get('.card_abc123').should('exist')
+// Better: add data-testid in the component
+cy.get('[data-testid="hero-banner"]').should('be.visible');
 
-// ✅ Stable — matches the un-hashed segment
-cy.get('[class*="_card_"]').should('exist')
-cy.get('[class*="_card_"]').first().click()
-
-// ✅ Better — add data-testid to the component and target that
-cy.get('[data-testid="hero-banner"]').should('be.visible')
+// Acceptable fallback for CSS Modules
+cy.get('[class*="_card_"]').first().click();
 ```
 
-**Preferred approach**: add `data-testid` attributes to component root elements in production views. They survive CSS Module renaming and minification:
+Preferred approach in production views:
 
 ```tsx
-// In default.server.tsx
 <section data-testid="hero-banner" className={styles.hero}>
 ```
 
 ---
 
-## Step 7 — Locale assertions
+## Step 7 — Organize support code cleanly
 
-Always test at least EN and FR. Use `cy.visit` with the locale prefix for FR:
+- Keep `cypress/support/commands.ts` focused on command registration.
+- Move larger helper implementations into small modules under `cypress/support/`.
+- Put run-level cleanup in `support/e2e.ts` so repeated runs stay idempotent.
+- Avoid large copy-pasted setup blocks across spec files.
 
-```typescript
-// EN (default)
-cy.visit(`/sites/${SITE_KEY}/home/testPage.html`)
+---
 
-// FR
-cy.visit(`/fr/sites/${SITE_KEY}/home/testPage.html`)
+## Guardrails
 
-// Assert locale-specific content
-cy.contains('Découvrir plus')  // FR CTA label
-```
+1. Never test against production data — always create isolated sites and fixtures.
+2. Always clean up created sites and users in `after()` hooks.
+3. Publish seeded content before asserting live renders.
+4. Prefer `data-testid` selectors over CSS classes.
+5. Avoid flaky `cy.wait(ms)` calls — use polling helpers or explicit conditions instead.
+6. Test both the happy path and the main failure/empty-state paths.
+7. Verify at least one secondary locale such as FR when the component is localized.
 
 ---
 
-## `@jahia/cypress` API reference
-
-| Function | Import | Purpose |
-|---|---|---|
-| `cy.login()` | built-in command | Log in as root (uses `SUPER_USER_PASSWORD` env var, default `root1234`) |
-| `cy.logout()` | built-in command | Log out |
-| `cy.apollo({ mutationFile, variables })` | built-in command | Execute a GraphQL mutation from a fixture file |
-| `cy.runProvisioningScript({ script })` | built-in command | Run a Jahia provisioning YAML |
-| `createSite(siteKey, options)` | `@jahia/cypress` | Create a site programmatically |
-| `deleteSite(siteKey)` | `@jahia/cypress` | Delete a site (use in `after`) |
-| `addNode(variables)` | `@jahia/cypress` | Create a JCR node via GraphQL |
-| `publishAndWaitJobEnding(path, locales?)` | `@jahia/cypress` | Publish content and block until the job completes |
-| `uploadFile(path, target, name, mimeType)` | `@jahia/cypress` | Upload a file to the JCR |
+## Running tests
 
-`createSite` options:
+```bash
+# From the module root
+yarn build && yarn jahia-deploy
 
-```typescript
-createSite(SITE_KEY, {
-    templateSet: 'my-module',      // module name
-    locale: 'en',                  // default locale
-    languages: 'en,fr',           // all activated locales (comma-separated)
-    serverName: 'localhost',
-})
+# Then run Cypress
+cd tests && yarn e2e:ci
 ```
 
----
-
-## Common pitfalls
-
-| Pitfall | Consequence |
-|---|---|
-| Missing `publishAndWaitJobEnding` after seeding | Tests run against unpublished content; live page returns stale or empty render |
-| Targeting hashed CSS Module class names directly | Tests break on every rebuild |
-| Skipping FR assertions | i18n regressions go undetected |
-| No `after` hook to delete the site | Test sites accumulate on the Jahia instance and pollute subsequent runs |
-| Running `createSite` without first deleting — no teardown in prior run | Site creation fails because the key already exists |
-| Relying on a pre-existing site instead of seeding | Tests are not self-contained and fail on a clean Jahia instance |
-| Not wrapping login/logout in `beforeEach`/`afterEach` | Session bleeds across tests; order-dependent failures |
+Use `yarn e2e:debug` locally when you need the interactive runner.
 
 ---
 
-## Running tests
-
-```bash
-# Against local Jahia (http://localhost:8080)
-cd tests
-yarn e2e:debug    # opens Cypress UI
-yarn e2e:ci       # headless, for CI
-```
+## Related skills
 
-Jahia must be running and the module deployed before running tests. Deploy first:
+- `/jahia-dev-build-component` — build the component being tested
+- `/jahia-dev-accessibility` — catch semantic and keyboard issues before or after writing e2e tests
+- `/jahia-dev-create-page-template` — create the page templates that Cypress will exercise
 
-```bash
-# From module root
-yarn build && yarn jahia-deploy
-# Then run tests
-cd tests && yarn e2e:ci
-```