Docs Testing

docs-testing Skill

Part 1: Decision Table — What to Run

Identify the changed file type and run the corresponding commands. Pre-commit hooks run automatically; "Run locally" items require manual invocation before or after committing.

Shared content rule: A change to content/shared/foo.md affects every product that has source: /shared/foo.md in a stub. Run the lint commands against the shared file; the CI link-checker and Vale resolve stubs to products automatically.

Part 2: Automation Coverage

Do not re-run these manually — they run automatically.

Pre-commit (lefthook.yml)

Runs on git commit against staged files:

• deprecated-markdown-patterns — banned shortcodes, py fence identifier
• check-support-links — non-standard support.influxdata.com URLs
• check-source-paths — source: must start with /shared/
• check-render-hook-whitespace — whitespace leaks in render hooks
• check-feedback-links — data/products.yml product feedback URLs
• Vale per-product — one hook per product, matches its content glob
• lint-markdown-instructions + lint-instructions — remark + Vale for repo docs
• build-typescript — compiles assets/js/*.ts
• prettier — formats JS/CSS/TS (auto-staged)
• lint-js — ESLint on assets/js/
• shellcheck — shell script lint

Pre-push (lefthook.yml)

Runs on git push:

• packages-audit — yarn audit (fails on default branch only)
• e2e-shortcode-examples — Cypress shortcode test (triggers on asset/layout/example.md changes)

Code block execution tests are disabled in pre-push hooks. Run them manually.

CI checks on every PR

Code block execution is NOT a PR check. It runs on demand via workflow_dispatch.

Dependency updates (org-managed)

Dependabot runs org-wide for all influxdata repos — it is managed by the security team, not by a workflow in this repo. Do not add a parallel dependency-update mechanism. Two implications for agents:

• When you add or update a third-party GitHub Action, pin it by full commit SHA with a version comment (see .github/workflows/pr-lockfile-lint.yml) so Dependabot can bump it cleanly.
• A repo-level .github/dependabot.yml, if present, supplements the org config; scheduled github-actions version updates require an explicit entry there. Coordinate with the security team before changing dependency automation.

Part 3: Running Specific Tests

Load this section only when you need to run a specific test type.

Codeblock lint (parse/compile)

# Single file or glob
yarn lint-codeblocks content/influxdb3/core/admin/tokens/admin/*.md

# Compact summary (counts by severity, top failing files)
yarn lint-codeblocks:pretty content/**/*.md

# Self-tests
yarn test:lint-codeblocks

Exit code 1 if any JSON/YAML/TOML/LP block fails to parse. bash/python/JS failures are warnings only.

lp validates InfluxDB line protocol, including qualified field keys such as family::field. Use {lint="false"} only for intentionally invalid examples.

Linter normalizes { placeholders="..." } fence attributes and strips Hugo shortcodes inside fences before parsing.

Code block execution (pytest)

Prerequisites: Docker installed, docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest ., .env.test file in the product directory.

yarn test:codeblocks:influxdb3_core
yarn test:codeblocks:influxdb3_enterprise
yarn test:codeblocks:telegraf
yarn test:codeblocks:v2
yarn test:codeblocks:cloud
yarn test:codeblocks:all

For InfluxDB 3 Core/Enterprise local server setup: see the influxdb3-test-setup skill.

For CI manual dispatch:

gh workflow run "Test Code Blocks" \
  --repo influxdata/docs-v2 \
  -f products=core,telegraf \
  -f use_default_group=false

Link validation

# Map content file(s) to HTML paths, then check
link-checker map content/influxdb3/core/get-started/ | xargs link-checker check

# Changed files in last commit
git diff --name-only HEAD~1 HEAD | grep '\.md$' | \
  xargs link-checker map | xargs link-checker check

# With production config (same as CI)
link-checker check \
  --config .ci/link-checker/production.lycherc.toml \
  public/path/to/page/

macOS: build from source (cargo build --release in docs-tooling/link-checker).

Vale style linting

# Default config
.ci/vale/vale.sh content/influxdb3/core/**/*.md

# Product-specific config
.ci/vale/vale.sh \
  --config=content/influxdb3/cloud-dedicated/.vale.ini \
  --minAlertLevel=error \
  content/influxdb3/cloud-dedicated/write-data/**/*.md

# Repo docs (DOCS-*.md, .github/, .claude/)
.ci/vale/vale.sh --config=.vale-instructions.ini README.md

Vocabulary edits: .ci/vale/styles/config/vocabularies. Rule authoring: see vale-linting skill and vale-rule-config skill.

Cypress E2E tests

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

# Run a specific spec (no content mapping)
node cypress/support/run-e2e-specs.js \
  --spec "cypress/e2e/content/jsonld-organization.cy.js" \
  --no-mapping

# Shortcode examples
yarn test:shortcode-examples

# All E2E tests
yarn test:e2e

The runner manages Hugo on port 1315 automatically. For writing Cypress tests: see cypress-e2e-testing skill.

Markdown generation validation

# Build prerequisites
yarn build:ts
npx hugo --quiet

# Generate markdown for a path
yarn build:md --public-dir public --path influxdb3/core/get-started --limit 10

# Validate output
node cypress/support/run-e2e-specs.js \
  --spec "cypress/e2e/content/markdown-content-validation.cy.js"

# Check autodiscovery coherence (run after full build:md)
yarn check:md-coherence

Part 4: Known Coverage Gaps

Flag these when writing or reviewing content in affected areas.

References

• Full contributor testing guide: DOCS-TESTING.md
• Cypress test writing: cypress-e2e-testing skill
• Vale rule authoring: vale-linting skill, vale-rule-config skill
• InfluxDB 3 local server setup: influxdb3-test-setup skill
• LLM markdown generation: scripts/README.md
• Code block test performance: test/TEST-PERFORMANCE.md