Skip to content

Commit d5d78ba

Browse files
dotnetprofessionalCopilot
dotnetprofessional
and
Copilot
committed
docs: add CI/CD guides with real-world learnings
- New xUnit CI/CD guide with journey test cross-platform gotchas, build config matching, and GitHub Pages deployment - Vitest CI/CD guide: added allowOnly, fileParallelism, and dynamic test CI-specific configuration section - Viewer CI/CD guide: added GitHub Pages static report deployment with environment setup instructions - All guides include troubleshooting tables from real CI debugging Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent df5dfdb commit d5d78ba

File tree

4 files changed

+555
-8
lines changed

4 files changed

+555
-8
lines changed

‎docs/docs/viewer/guides/ci-cd-dashboards.mdx‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,123 @@ export default defineConfig({
225225

226226
---
227227

228+
## Deploying Static Reports to GitHub Pages
229+
230+
For a permanent, browsable URL hosting your test reports, deploy the static
231+
HTML export to GitHub Pages. This combines the Viewer's `export` command with
232+
GitHub's free static hosting.
233+
234+
### Complete Workflow
235+
236+
```yaml
237+
name: LiveDoc Report
238+
239+
on:
240+
push:
241+
branches: [main]
242+
workflow_dispatch:
243+
244+
permissions:
245+
contents: read
246+
pages: write
247+
id-token: write
248+
249+
concurrency:
250+
group: pages
251+
cancel-in-progress: true
252+
253+
jobs:
254+
generate-reports:
255+
runs-on: ubuntu-latest
256+
257+
steps:
258+
- uses: actions/checkout@v4
259+
260+
- uses: actions/setup-node@v4
261+
with:
262+
node-version: 22
263+
264+
- name: Install dependencies
265+
run: npm ci
266+
267+
- name: Run tests with JSON export
268+
run: npx vitest run
269+
# Assumes vitest.config.ts has LiveDocSpecReporter with export option
270+
271+
- name: Generate HTML report
272+
if: always()
273+
run: npx @swedevtools/livedoc-viewer export -i ./test-results/livedoc-report.json -o ./reports/index.html -t "My Project"
274+
275+
- name: Setup Pages
276+
if: always()
277+
uses: actions/configure-pages@v5
278+
279+
- name: Upload Pages artifact
280+
if: always()
281+
uses: actions/upload-pages-artifact@v3
282+
with:
283+
path: reports
284+
285+
deploy:
286+
needs: generate-reports
287+
runs-on: ubuntu-latest
288+
environment:
289+
name: github-pages
290+
url: ${{ steps.deployment.outputs.page_url }}
291+
steps:
292+
- id: deployment
293+
uses: actions/deploy-pages@v4
294+
```
295+
296+
### GitHub Pages Setup
297+
298+
Before the deploy job will succeed, configure your repository:
299+
300+
1. **Settings → Pages**: Set Source to **GitHub Actions** (not "Deploy from a branch")
301+
2. **Settings → Environments**: Ensure a `github-pages` environment exists
302+
3. **Environment branch rules**: If you have branch protection on the `github-pages`
303+
environment, add your deployment branch (e.g., `main`) to the allowed list
304+
305+
:::danger Environment must exist
306+
The deploy job references `environment: name: github-pages`. If this environment
307+
doesn't exist in your repo settings, the job fails silently — it won't even be
308+
assigned a runner. Go to **Settings → Environments → New environment** and name
309+
it exactly `github-pages`.
310+
:::
311+
312+
### Multi-Project Landing Page
313+
314+
If you run both TypeScript (Vitest) and .NET (xUnit) tests, create a landing
315+
page that links to both reports:
316+
317+
```yaml
318+
- name: Create index page
319+
if: always()
320+
run: |
321+
cat > reports/index.html << 'EOF'
322+
<!DOCTYPE html>
323+
<html>
324+
<head><title>Test Reports</title></head>
325+
<body>
326+
<h1>Test Reports</h1>
327+
<ul>
328+
<li><a href="./vitest/">Vitest Report</a></li>
329+
<li><a href="./dotnet/">xUnit Report</a></li>
330+
</ul>
331+
</body>
332+
</html>
333+
EOF
334+
```
335+
336+
Generate each report into its own subdirectory:
337+
338+
```bash
339+
npx @swedevtools/livedoc-viewer export -i vitest-report.json -o reports/vitest/index.html
340+
npx @swedevtools/livedoc-viewer export -i dotnet-report.json -o reports/dotnet/index.html
341+
```
342+
343+
---
344+
228345
## Troubleshooting
229346

230347
| Problem | Cause | Solution |
@@ -234,6 +351,9 @@ export default defineConfig({
234351
| Port conflict | Another service on 3100 | Use `--port <other>` |
235352
| Results empty after run | Reporter not configured | Verify `LiveDocViewerReporter` is in the config |
236353
| Health check times out | Viewer hasn't started yet | Increase the retry count in the wait loop |
354+
| Pages deploy fails immediately | `github-pages` environment missing | Create it in Settings → Environments |
355+
| Pages deploy "not authorized" | Branch not in environment rules | Add your branch to the `github-pages` environment's deployment branch rules |
356+
| Static report shows "Run in progress" | Stale status in exported data | Update to latest `@swedevtools/livedoc-viewer` — fixed in the static export mode |
237357

238358
---
239359

‎docs/docs/vitest/guides/ci-cd.mdx‎

Lines changed: 68 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,68 @@ Register in your config:
120120
setupFiles: ['./test/livedoc.setup.ts'],
121121
```
122122

123-
## Step 4: Create a GitHub Actions Workflow
123+
## Step 4: CI-Specific Vitest Configuration
124+
125+
GitHub Actions and most CI providers set the `CI=true` environment variable.
126+
This changes Vitest's defaults in ways that affect LiveDoc. Create a dedicated
127+
CI config to handle these differences:
128+
129+
```typescript
130+
// vitest.config.ci.ts
131+
import { defineConfig, mergeConfig } from 'vitest/config';
132+
import baseConfig from './vitest.config';
133+
134+
export default mergeConfig(
135+
baseConfig,
136+
defineConfig({
137+
test: {
138+
allowOnly: true,
139+
pool: 'forks',
140+
fileParallelism: false,
141+
},
142+
})
143+
);
144+
```
145+
146+
Then run tests with this config in CI:
147+
148+
```yaml
149+
- name: Run LiveDoc tests
150+
run: npx vitest run --config vitest.config.ci.ts
151+
```
152+
153+
:::danger `allowOnly` is required
154+
When `CI=true`, Vitest defaults `allowOnly` to `false` — meaning any
155+
`describe.only()` or `it.only()` call throws an error. LiveDoc's tag-based
156+
filtering uses `describe.only()` internally to select matching tests. Without
157+
`allowOnly: true`, **all tag-filtered tests will fail in CI** with:
158+
159+
```
160+
Error: Vitest is running with config.allowOnly set to false.
161+
```
162+
:::
163+
164+
:::caution Parallel execution and dynamic tests
165+
If your test suite uses LiveDoc's dynamic test features (e.g., `executeDynamicTestAsync`),
166+
you should disable file parallelism in CI. Dynamic tests spawn nested Vitest
167+
instances, and running multiple nested instances in parallel causes resource
168+
contention — flaky failures, missing results, or hangs.
169+
170+
Setting `pool: 'forks'` and `fileParallelism: false` ensures each test file
171+
runs sequentially in its own process, avoiding these issues:
172+
173+
```typescript
174+
test: {
175+
pool: 'forks', // Process isolation (not threads)
176+
fileParallelism: false, // One file at a time
177+
}
178+
```
179+
180+
This only affects CI — your local development can still use the default parallel
181+
execution for speed.
182+
:::
183+
184+
## Step 5: Create a GitHub Actions Workflow
124185

125186
```yaml
126187
# .github/workflows/livedoc-tests.yml
@@ -148,9 +209,7 @@ jobs:
148209
run: npm ci
149210
150211
- name: Run LiveDoc tests
151-
run: npx vitest run
152-
env:
153-
CI: 'true'
212+
run: npx vitest run --config vitest.config.ci.ts
154213
155214
- name: Generate HTML report
156215
if: always()
@@ -170,7 +229,7 @@ jobs:
170229
The `if: always()` on the export and upload steps ensures results are captured
171230
even when tests fail.
172231

173-
## Step 5: Write Output to a Log File
232+
## Step 6: Write Output to a Log File
174233

175234
For human-readable test output in CI logs, add file output:
176235

@@ -255,9 +314,7 @@ jobs:
255314
run: npm ci
256315
257316
- name: Run LiveDoc tests
258-
run: npx vitest run
259-
env:
260-
CI: 'true'
317+
run: npx vitest run --config vitest.config.ci.ts
261318
262319
- name: Generate HTML report
263320
if: always()
@@ -356,6 +413,9 @@ livedoc-tests:
356413
| No test output in CI logs | `detailLevel: 'silent'` | Change to `'spec+summary+headers'` for visible output |
357414
| Artifact upload fails | Wrong path | Verify the `path` in `upload-artifact` matches your `json-output` path |
358415
| Slow tests in CI | No tag filtering | Add `@slow` tags and exclude them with `livedoc.options.filters.exclude` |
416+
| `config.allowOnly` error | `CI=true` disables `.only()` | Add `allowOnly: true` to your CI vitest config |
417+
| Dynamic tests fail/hang in CI | Parallel nested Vitest instances | Use `pool: 'forks'` and `fileParallelism: false` in CI config |
418+
| `--config` ignored via pnpm filter | Double `--config` argument | Use `npx vitest run --config ...` directly instead of `pnpm --filter pkg test -- --config` |
359419

360420
## Related
361421

0 commit comments

Comments
 (0)