Cypress E2e Testing

Cypress E2E Testing Skill

Purpose

This skill guides agents through running Cypress end-to-end tests for the documentation site, including understanding when Hugo starts automatically vs. manually, interpreting test results, and debugging failures.

For comprehensive testing documentation, see DOCS-TESTING.md.

Key Insight: Hugo Server Management

The test runner (run-e2e-specs.js) automatically manages Hugo.

• Port 1315 is used for testing (not 1313)
• If port 1315 is free → starts Hugo automatically
• If port 1315 is in use → checks if it's a working Hugo server and reuses it
• Hugo logs written to /tmp/hugo_server.log

You do NOT need to start Hugo separately unless you want to keep it running between test runs for faster iteration.

Quick Reference

Prerequisites

# Install dependencies (required)
yarn install

# Verify Cypress is available
yarn cypress --version

API Reference Tests: Additional Prerequisites

API reference pages require generation before testing. The pages don't exist until you run:

# Generate API documentation content from OpenAPI specs
yarn build:api-docs

This step:

• Processes OpenAPI specs in api-docs/ directories
• Generates Hugo content pages in content/*/api/
• Creates operation pages, tag pages, and index pages

Without this step, all API reference tests will fail with 404 errors.

Quick check - verify API content exists:

# Should list generated API content directories
ls content/influxdb3/core/api/

# If "No such file or directory", run: yarn build:api-docs

Markdown Validation Tests: Additional Prerequisites

Markdown validation tests require generated markdown files. Run:

# Build Hugo site first (generates HTML in public/)
npx hugo --quiet

# Generate LLM-friendly markdown from HTML
yarn build:md

This creates .md files in the public/ directory that the markdown validation tests check.

Without this step, markdown validation tests will fail with missing file errors.

Test Execution Modes

Mode 1: Content-Specific Tests (Default)

Tests specific content files by mapping them to URLs.

# Single file
node cypress/support/run-e2e-specs.js content/influxdb3/core/_index.md

# Multiple files
node cypress/support/run-e2e-specs.js content/influxdb3/core/_index.md content/influxdb3/enterprise/_index.md

# With specific test spec
node cypress/support/run-e2e-specs.js \
  --spec "cypress/e2e/content/api-reference.cy.js" \
  content/influxdb3/core/reference/api/_index.md

What happens:

1. Maps content files to URLs (e.g., content/influxdb3/core/_index.md → /influxdb3/core/)
2. Starts Hugo on port 1315 (if not running)
3. Runs Cypress tests against mapped URLs
4. Stops Hugo when done

Mode 2: Functionality Tests (--no-mapping)

Tests UI functionality without requiring content file paths.

# Run functionality test
node cypress/support/run-e2e-specs.js \
  --spec "cypress/e2e/page-context.cy.js" \
  --no-mapping

Use when: Testing JavaScript components, theme switching, navigation, or other UI behavior not tied to specific content.

Mode 3: Reusing an Existing Hugo Server

For faster iteration during development:

# Terminal 1: Start Hugo manually on port 1315
npx hugo server --port 1315 --environment testing --noHTTPCache

# Terminal 2: Run tests (will detect and reuse existing server)
node cypress/support/run-e2e-specs.js \
  --spec "cypress/e2e/content/api-reference.cy.js" \
  content/influxdb3/core/reference/api/_index.md

Available Test Specs

Understanding Test Output

Success Output

✅ e2e tests completed successfully
📊 Detailed Test Results:
   • Total Tests: 25
   • Tests Passed: 25
   • Tests Failed: 0

Failure Output

ℹ️ Note: 3 test(s) failed.
📊 Detailed Test Results:
   • Total Tests: 25
   • Tests Passed: 22
   • Tests Failed: 3

📋 Failed Spec Files:
   • cypress/e2e/content/api-reference.cy.js
     - Failures: 3
     - Failed Tests:
       * has API info
         Error: Expected to find element '.article--description'

Common Failure Patterns

Debugging Failures

Step 1: Check Hugo Logs

cat /tmp/hugo_server.log | tail -50

Look for:

• Template errors (error calling partial)
• Build failures
• Missing data files

Step 2: Run Test in Interactive Mode

# Start Hugo manually
npx hugo server --port 1315 --environment testing

# In another terminal, open Cypress interactively
yarn cypress open

Step 3: Inspect the Page

Visit http://localhost:1315/path/to/page/ in a browser and:

• Open DevTools Console for JavaScript errors
• Inspect elements to verify selectors
• Check Network tab for failed requests

Step 4: Run Single Test with Verbose Output

DEBUG=cypress:* node cypress/support/run-e2e-specs.js \
  --spec "cypress/e2e/content/api-reference.cy.js" \
  content/influxdb3/core/reference/api/_index.md

Test Configuration

The test runner uses these settings:

{
  browser: 'chrome',
  baseUrl: 'http://localhost:1315',
  video: false,  // Disabled in CI
  defaultCommandTimeout: 10000,  // 15000 in CI
  pageLoadTimeout: 30000,  // 45000 in CI
}

Writing New Tests

Basic Test Structure

describe('Feature Name', () => {
  beforeEach(() => {
    cy.visit('/path/to/page/');
  });

  it('validates expected behavior', () => {
    cy.get('.selector').should('exist');
    cy.get('.selector').should('be.visible');
    cy.get('.selector').contains('Expected text');
  });
});

Testing Components

describe('Component Name', () => {
  it('initializes correctly', () => {
    cy.visit('/path/with/component/');

    // Wait for component initialization
    cy.get('[data-component="my-component"]', { timeout: 5000 })
      .should('be.visible');

    // Verify component rendered expected elements
    cy.get('[data-component="my-component"] .child-element')
      .should('have.length.at.least', 1);
  });
});

Using Real Configuration Data

Import real configuration data (from data/*.yml) via cy.task('getData') instead of hardcoding expected values. This keeps tests in sync with the source of truth.

describe('Product shortcodes', function () {
  let products;

  before(function () {
    // Load products.yml via the getData task defined in cypress.config.js
    cy.task('getData', 'products').then((data) => {
      products = data;
    });
  });

  it('renders the correct product name', function () {
    cy.visit('/influxdb3/core/_test/shortcodes/');
    // Assert against YAML data, not a hardcoded string
    cy.get('[data-testid="product-name"]').should(
      'contain.text',
      products.influxdb3_core.name
    );
  });

  it('renders current-version from YAML', function () {
    cy.visit('/influxdb/v2/_test/shortcodes/');
    // Derive expected value the same way the Hugo shortcode does
    const patch = products.influxdb.latest_patches?.v2;
    const expected = patch ? patch.replace(/\.\d+$/, '') : '';
    cy.get('[data-testid="current-version"] .current-version').should(
      'have.text',
      expected
    );
  });
});

Key principles:

• Load YAML data in before() — available to all tests in the suite
• Derive expected values from the data, mirroring shortcode logic
• Only hardcode what you must: content paths and test page URLs
• Derive boolean flags from data fields (e.g., product.distributed_architecture, product.limits)

See cypress/e2e/content/shortcodes.cy.js and cypress/e2e/content/latest-patch-shortcode.cy.js for full examples.

Testing Links

it('contains valid internal links', () => {
  cy.get('body').then(($body) => {
    if ($body.find('a[href^="/"]').length === 0) {
      cy.log('No internal links found');
      return;
    }

    cy.get('a[href^="/"]').each(($a) => {
      cy.request($a.attr('href')).its('status').should('eq', 200);
    });
  });
});

Testing structured data (JSON-LD)

The layouts/partials/header/*-jsonld.html partials emit schema.org JSON-LD. The right assertions depend on the node's scope:

• Page-scoped nodes (TechArticle, SoftwareApplication) describe a specific page or product. Assert presence/shape where they belong and absence where they don't — the absence check guards against over-emission (e.g. a SoftwareApplication node leaking onto deep pages instead of only product landing roots).
• Global nodes (Organization) describe the site's single entity and are emitted site-wide with a stable @id. Assert exactly one per page across page classes — that catches both omission (a page class emitting nothing) and accidental duplicate emission.

Parse <script type="application/ld+json"> by @type, then assert. See cypress/e2e/content/jsonld-organization.cy.js and jsonld-techarticle.cy.js for the established pattern:

function ldByType(win$, doc, type) {
  return [...win$(doc).find('script[type="application/ld+json"]')]
    .map((s) => { try { return JSON.parse(s.textContent); } catch { return null; } })
    .filter((j) => j && j['@type'] === type);
}

// Page-scoped: present on the landing root, absent on a deep page.
it('emits SoftwareApplication on the product root, none on deep pages', () => {
  cy.visit('/influxdb3/core/');
  cy.document().then((doc) => {
    expect(ldByType(Cypress.$, doc, 'SoftwareApplication')).to.have.length(1);
  });
  cy.visit('/influxdb3/core/admin/');
  cy.document().then((doc) => {
    expect(ldByType(Cypress.$, doc, 'SoftwareApplication')).to.have.length(0);
  });
});

// Global: exactly one on every page class (hub, root, deep article).
it('emits exactly one Organization on a deep page', () => {
  cy.visit('/influxdb3/core/admin/');
  cy.document().then((doc) => {
    expect(ldByType(Cypress.$, doc, 'Organization')).to.have.length(1);
  });
});

Cypress proves the markup is emitted where intended. It does not validate schema correctness. For that, use the Schema Markup Validator (https://validator.schema.org) — not the Google Rich Results Test, which reports "no items detected" for Organization, TechArticle, and SoftwareApplication because they aren't rich-result types (only FAQPage is). See the hugo-template-dev skill, "Validating structured data (JSON-LD)".

CI/CD Considerations

In CI environments:

• Video recording is disabled to save resources
• Timeouts are increased (15s command, 45s page load)
• Memory management is enabled
• Only 1 test kept in memory at a time

Related Files

• Test runner: cypress/support/run-e2e-specs.js
• Hugo server helper: cypress/support/hugo-server.js
• URL mapper: cypress/support/map-files-to-urls.js
• Config: cypress.config.js
• Comprehensive docs: DOCS-TESTING.md

Checklist for Test Validation

Before concluding test analysis:

• For API tests: Verify yarn build:api-docs was run (check ls content/*/api/)
• All tests passed, or failures are understood
• Hugo logs checked for build errors
• Failed selectors verified against current templates
• Broken links identified and reported
• JavaScript console errors investigated (if relevant)
• For JSON-LD changes: presence/absence asserted in Cypress, and schema validated via validator.schema.org (not the Rich Results Test)

Related Skills

• hugo-template-dev - For Hugo template syntax, data access patterns, and runtime testing. Includes the PR preview-pages mechanism — when the change is visual or structural (canonical/meta tags, JSON-LD, head fragments, layout reflows) and Cypress is overkill, list affected URLs in the PR description so the preview workflow lands reviewers on the exact pages without local setup.
• docs-cli-workflow - For creating/editing documentation content with CLI tools
• ts-component-dev (agent) - TypeScript component behavior and interactivity
• hugo-ui-dev (agent) - Hugo templates and SASS/CSS styling