docs: add ci test for document structure #2935
Conversation
|
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughAdded docs build and page-structure validation to CI; introduced Vitest/happy-dom/Vite test tooling and configs for the docs app; extended VitePress auto-inject plugin to support root-level Markdown and frontmatter title; added a Vitest test that validates generated HTML header structure; removed a redundant H1 in one doc. Changes
Sequence Diagram(s)sequenceDiagram
participant CI as GitHub Actions CI
participant BuildJob as Build job
participant LibBuild as Library build
participant DocsBuild as Docs build (pnpm)
participant Dist as Built docs (dist/)
participant Vitest as Vitest (happy-dom)
participant Parser as HTML parser
CI->>BuildJob: trigger Build job
BuildJob->>LibBuild: build library
BuildJob->>DocsBuild: pnpm --filter docs run build
DocsBuild->>Dist: emit built HTML pages
BuildJob->>Vitest: pnpm --filter docs run test:unit:ci
Vitest->>Dist: read .html files
Vitest->>Parser: parse HTML (happy-dom)
Parser-->>Vitest: DOM & headers
Vitest->>Vitest: validate single root header per page
Vitest-->>BuildJob: pass/fail
BuildJob-->>CI: job status
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (2)
🧰 Additional context used🧠 Learnings (9)📓 Common learnings📚 Learning: 2025-11-30T17:09:16.288ZApplied to files:
📚 Learning: 2025-08-19T14:23:46.775ZApplied to files:
📚 Learning: 2025-09-30T23:57:21.526ZApplied to files:
📚 Learning: 2025-10-21T19:31:54.113ZApplied to files:
📚 Learning: 2025-11-30T17:09:16.288ZApplied to files:
📚 Learning: 2025-11-30T17:09:16.288ZApplied to files:
📚 Learning: 2025-11-30T17:09:16.288ZApplied to files:
📚 Learning: 2025-11-30T17:09:16.288ZApplied to files:
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🔇 Additional comments (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR adds automated CI testing to validate the document structure of built documentation pages, ensuring consistency required for the On-This-Page (OTP) sidebar generation. The changes include a new test suite that validates HTML output, updates to the auto-inject plugin to support frontmatter title overrides, and fixes for documents that failed validation.
Key Changes
- Added Vitest test infrastructure to the docs app to validate page header structure
- Created a comprehensive test that validates all built HTML pages have exactly one root header
- Enhanced the auto-inject plugin to support frontmatter
titlefield as an override - Fixed
BToggle.mdwhich had a duplicate header
Reviewed changes
Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
vitest.workspace.mjs |
Adds docs app to the Vitest workspace for test execution |
pnpm-lock.yaml |
Auto-generated lockfile updates for new dependencies (happy-dom, vitest) |
apps/docs/vite.config.mts |
New Vitest configuration for docs tests with happy-dom environment |
apps/docs/tsconfig.vitest.json |
TypeScript configuration for test files |
apps/docs/tsconfig.json |
References the new vitest TypeScript config |
apps/docs/tests/page-structure.test.ts |
New test suite that validates page header structure matches runtime expectations |
apps/docs/src/docs/directives/BToggle.md |
Removed duplicate h1 header (was causing validation failure) |
apps/docs/package.json |
Added test scripts and dependencies (happy-dom, vitest, vite) |
apps/docs/.vitepress/plugins/auto-inject-doc-components.ts |
Enhanced to support frontmatter title override and root-level markdown files |
.github/workflows/ci.yaml |
Added docs page structure validation step to CI pipeline |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
apps/docs/vite.config.mts (1)
1-9: Consider using modern Vitest config import pattern.The triple-slash reference works but is the older pattern. Vitest 1.x+ recommends importing from
vitest/configfor better type safety:-/// <reference types="vitest" /> - -import {defineConfig} from 'vite' +import {defineConfig} from 'vitest/config' export default defineConfig({ test: { environment: 'happy-dom', include: ['tests/**/*.test.ts'], }, })
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (9)
.github/workflows/ci.yaml(1 hunks)apps/docs/.vitepress/plugins/auto-inject-doc-components.ts(3 hunks)apps/docs/package.json(2 hunks)apps/docs/src/docs/directives/BToggle.md(0 hunks)apps/docs/tests/page-structure.test.ts(1 hunks)apps/docs/tsconfig.json(1 hunks)apps/docs/tsconfig.vitest.json(1 hunks)apps/docs/vite.config.mts(1 hunks)vitest.workspace.mjs(1 hunks)
💤 Files with no reviewable changes (1)
- apps/docs/src/docs/directives/BToggle.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx,js,jsx,vue}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Use conventional commit format with prefixes like
feat:,fix:,docs:, etc. for all commits
Files:
apps/docs/tests/page-structure.test.ts
🧠 Learnings (8)
📓 Common learnings
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Always validate changes before committing: run `pnpm --filter bootstrap-vue-next run test:lint`, then `pnpm --filter bootstrap-vue-next run test:unit:ci`, then `pnpm --filter bootstrap-vue-next run build` to ensure linting, tests pass, and code is buildable
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Always validate changes before committing: run `pnpm --filter bootstrap-vue-next run test:lint`, then `pnpm --filter bootstrap-vue-next run test:unit:ci`, then `pnpm --filter bootstrap-vue-next run build` to ensure linting, tests pass, and code is buildable
Applied to files:
apps/docs/package.jsonapps/docs/tests/page-structure.test.ts.github/workflows/ci.yaml
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Docs build fails due to OpenCollective API calls (expected). Use `pnpm install --ignore-scripts` to skip problematic prepare scripts and filter builds to specific packages using `pnpm --filter bootstrap-vue-next run build` to avoid docs build failures
Applied to files:
apps/docs/package.json.github/workflows/ci.yaml
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: NEVER CANCEL build or test commands - set timeouts to 60+ minutes. Individual command timings: `pnpm install --ignore-scripts --frozen-lockfile` (~2s), `pnpm --filter bootstrap-vue-next run build` (~27s), `pnpm --filter bootstrap-vue-next run test:unit:ci` (~40s), `pnpm --filter bootstrap-vue-next run test:lint` (~12s)
Applied to files:
apps/docs/package.json.github/workflows/ci.yaml
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Applies to packages/bootstrap-vue-next/src/components/**/*.vue : Edit component files in `packages/bootstrap-vue-next/src/components/` and test using `packages/bootstrap-vue-next/src/App.vue` with hot-reload via `pnpm --filter bootstrap-vue-next run dev`
Applied to files:
apps/docs/package.jsonapps/docs/tsconfig.vitest.json.github/workflows/ci.yamlvitest.workspace.mjs
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Applies to packages/bootstrap-vue-next/src/components/**/*.spec.ts : Write tests for new components following existing test patterns in `.spec.ts` files
Applied to files:
apps/docs/tsconfig.vitest.jsonapps/docs/vite.config.mtsapps/docs/tests/page-structure.test.ts
📚 Learning: 2025-10-28T03:37:33.172Z
Learnt from: dwgray
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 2891
File: apps/docs/.vitepress/plugins/auto-inject-doc-components.ts:106-130
Timestamp: 2025-10-28T03:37:33.172Z
Learning: In apps/docs/.vitepress/plugins/auto-inject-doc-components.ts, the documentation injection logic is intentionally simple and does not need to handle edge cases like partial presence of ComponentReference/imports, existing <script setup> blocks, or nested component directories. The codebase does not use these patterns and does not expect to support them.
Applied to files:
apps/docs/tsconfig.vitest.jsonapps/docs/tests/page-structure.test.tsapps/docs/.vitepress/plugins/auto-inject-doc-components.ts
📚 Learning: 2025-08-19T23:30:52.911Z
Learnt from: dwgray
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 2762
File: apps/docs/src/docs/components/tooltip.md:0-0
Timestamp: 2025-08-19T23:30:52.911Z
Learning: VitePress .data.ts files use build-time data loading where the file exports a default object with a load() function, and VitePress processes this at build time to make the loaded data available as a named export {data}. The correct import syntax is `import {data} from './file.data'`, not a default import, even though the .data.ts file itself uses export default.
Applied to files:
apps/docs/vite.config.mtsvitest.workspace.mjs
🧬 Code graph analysis (1)
apps/docs/tests/page-structure.test.ts (2)
apps/docs/eslint.config.mjs (1)
__dirname(7-7)apps/docs/src/types/index.ts (1)
HeaderItem(104-104)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Agent
- GitHub Check: build
🔇 Additional comments (9)
apps/docs/package.json (2)
14-16: LGTM! Test scripts follow project conventions.The test script structure (
test:unit,test:unit:ci, combinedtest) aligns well with the patterns used in other packages in this monorepo, as noted in the retrieved learnings.
37-42: Appropriate testing dependencies added.The combination of
vitest,vite, andhappy-domis well-suited for testing documentation structure in a lightweight DOM environment without needing a full browser.apps/docs/.vitepress/plugins/auto-inject-doc-components.ts (2)
64-70: Root-level matching is appropriately guarded by frontmatter check.The
rootMatchpattern is permissive but the frontmatterdescriptioncheck on line 105 ensures only intended documentation files are processed. This follows the intentionally simple design noted in past discussions.
109-110: Clean title resolution with frontmatter override.The fallback chain (
frontmatter.title || filenameToTitle(...)) provides flexibility for root-level files that may not follow the kebab-case naming convention while maintaining backward compatibility for existing docs.apps/docs/tsconfig.json (1)
9-12: LGTM! Proper TypeScript project reference added.The vitest tsconfig reference follows the existing project references pattern for the docs app.
apps/docs/tsconfig.vitest.json (1)
1-9: Verify test import style matches globals configuration.The
vitest/globalstype is included in tsconfig.vitest.json, but verification requires checking whetherglobals: trueis set invite.config.mts. Ensure your tests either:
- Use explicit imports:
import { describe, it, expect } from 'vitest', or- Add
globals: trueto the test config if you prefer global APIsvitest.workspace.mjs (1)
1-8: LGTM!The workspace configuration correctly adds the docs app vite config, enabling the new page structure tests to run as part of the vitest workspace.
.github/workflows/ci.yaml (1)
52-54: LGTM!The new CI step is correctly positioned after the build step, ensuring the docs are built before validating the page structure. The pnpm filter syntax correctly targets the docs package.
apps/docs/tests/page-structure.test.ts (1)
141-189: Well-structured test suite.The test design is solid:
- First test provides a clear error message when build is missing
- Second test aggregates all validation failures for easier debugging
- Skip patterns correctly exclude special pages
- The 30s timeout is appropriate for processing multiple HTML files
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.github/workflows/ci.yaml(2 hunks)apps/docs/tests/page-structure.test.ts(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx,js,jsx,vue}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Use conventional commit format with prefixes like
feat:,fix:,docs:, etc. for all commits
Files:
apps/docs/tests/page-structure.test.ts
🧠 Learnings (8)
📓 Common learnings
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Always validate changes before committing: run `pnpm --filter bootstrap-vue-next run test:lint`, then `pnpm --filter bootstrap-vue-next run test:unit:ci`, then `pnpm --filter bootstrap-vue-next run build` to ensure linting, tests pass, and code is buildable
Learnt from: dwgray
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 2891
File: apps/docs/.vitepress/plugins/auto-inject-doc-components.ts:106-130
Timestamp: 2025-10-28T03:37:33.172Z
Learning: In apps/docs/.vitepress/plugins/auto-inject-doc-components.ts, the documentation injection logic is intentionally simple and does not need to handle edge cases like partial presence of ComponentReference/imports, existing <script setup> blocks, or nested component directories. The codebase does not use these patterns and does not expect to support them.
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Always validate changes before committing: run `pnpm --filter bootstrap-vue-next run test:lint`, then `pnpm --filter bootstrap-vue-next run test:unit:ci`, then `pnpm --filter bootstrap-vue-next run build` to ensure linting, tests pass, and code is buildable
Applied to files:
.github/workflows/ci.yamlapps/docs/tests/page-structure.test.ts
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Docs build fails due to OpenCollective API calls (expected). Use `pnpm install --ignore-scripts` to skip problematic prepare scripts and filter builds to specific packages using `pnpm --filter bootstrap-vue-next run build` to avoid docs build failures
Applied to files:
.github/workflows/ci.yaml
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: NEVER CANCEL build or test commands - set timeouts to 60+ minutes. Individual command timings: `pnpm install --ignore-scripts --frozen-lockfile` (~2s), `pnpm --filter bootstrap-vue-next run build` (~27s), `pnpm --filter bootstrap-vue-next run test:unit:ci` (~40s), `pnpm --filter bootstrap-vue-next run test:lint` (~12s)
Applied to files:
.github/workflows/ci.yaml
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Applies to packages/bootstrap-vue-next/src/components/**/*.vue : Edit component files in `packages/bootstrap-vue-next/src/components/` and test using `packages/bootstrap-vue-next/src/App.vue` with hot-reload via `pnpm --filter bootstrap-vue-next run dev`
Applied to files:
.github/workflows/ci.yaml
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Use ONLY pnpm as the package manager (version 10.13.1), never npm or yarn. Always use `--frozen-lockfile` for reproducible installs and workspace filters `--filter <package-name>` for targeted operations
Applied to files:
.github/workflows/ci.yaml
📚 Learning: 2025-11-30T17:09:16.288Z
Learnt from: CR
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-30T17:09:16.288Z
Learning: Applies to packages/bootstrap-vue-next/src/components/**/*.spec.ts : Write tests for new components following existing test patterns in `.spec.ts` files
Applied to files:
apps/docs/tests/page-structure.test.ts
📚 Learning: 2025-10-28T03:37:33.172Z
Learnt from: dwgray
Repo: bootstrap-vue-next/bootstrap-vue-next PR: 2891
File: apps/docs/.vitepress/plugins/auto-inject-doc-components.ts:106-130
Timestamp: 2025-10-28T03:37:33.172Z
Learning: In apps/docs/.vitepress/plugins/auto-inject-doc-components.ts, the documentation injection logic is intentionally simple and does not need to handle edge cases like partial presence of ComponentReference/imports, existing <script setup> blocks, or nested component directories. The codebase does not use these patterns and does not expect to support them.
Applied to files:
apps/docs/tests/page-structure.test.ts
🧬 Code graph analysis (1)
apps/docs/tests/page-structure.test.ts (2)
apps/docs/eslint.config.mjs (1)
__dirname(7-7)apps/docs/src/types/index.ts (1)
HeaderItem(104-104)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build
🔇 Additional comments (6)
.github/workflows/ci.yaml (2)
52-56: LGTM! Past ordering concern resolved.The docs build now correctly precedes validation, addressing the previous review comment. The workflow properly builds the docs artifacts before running structure validation tests.
136-136: LGTM! Proper test separation.Excluding docs from the general unit test run is appropriate since docs tests are run separately in their own step with the required build artifacts.
apps/docs/tests/page-structure.test.ts (4)
1-11: LGTM! Appropriate setup.Imports and directory configuration are correct. The
__dirnamepattern matches existing conventions in the docs codebase.
23-127: LGTM! Past cleanup concerns fully addressed.The try-finally block ensures
window.close()is always called, even when returning early at line 44. Previous review concerns about resource cleanup have been properly resolved.
132-146: LGTM! Standard recursive traversal.The recursive HTML file finder follows standard patterns and is appropriate for the test context.
148-154: LGTM! Clear precondition check.The directory existence test provides helpful guidance if the build hasn't been run, improving developer experience.
VividLemon
left a comment
VividLemon
left a comment
There was a problem hiding this comment.
Probably just make that upgrade the bot talked about, besides that looks fine
2 participants
Describe the PR
The changes I made to build the OTTP sidebar from the document structure are somewhat fragile by design - we want a consistent structure. But the only error was a log in the console and the absence of a useful OTP sidebar.
This change adds a CI test to verify the document structure. I looked at lighter-weight ways to do this at build time, but none worked because we’re pulling the document structure from various places, so we don’t have a verifiable structure until the build is complete. Running a test against the built site seems like the most reliable way to verify that the OTP sidebars will work.
Also fixed a couple of documents that the test caught.
Small replication
See documentation.
PR checklist
What kind of change does this PR introduce? (check at least one)
fix(...)feat(...)fix(...)docs(...)The PR fulfills these requirements:
CHANGELOGis generated from these messages, and determines the next version type. Pull requests that do not follow conventional commits or do not have an override will be deniedSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.