By name: quarto-preview-test description: Use when testing preview functionality, verifying live reload, or validating preview fixes. Covers starting preview with port/logging, browser verification via /agent-browser, and checking logs/filesystem for artifacts.
Quarto Preview Test
Interactive testing of quarto preview with automated browser verification.
Tools
| Tool | When to use |
|---|---|
/agent-browser |
Preferred. Token-efficient browser automation. Navigate, verify content, screenshot. |
| Chrome DevTools MCP | Deep debugging: console messages, network requests, DOM inspection. |
jq / grep |
Parse debug log output. |
Prerequisites
- Quarto dev version built (
./configure.shor./configure.cmd) - Test environment configured (
tests/configure-test-env.shortests/configure-test-env.ps1) /agent-browserCLI installed (preferred), OR Chrome + Chrome DevTools MCP connected
Starting Preview
Preview needs the test venv for Jupyter tests. Activate it first (tests/.venv), matching how run-tests.sh / run-tests.ps1 do it.
# Linux/macOS
source tests/.venv/bin/activate
./package/dist/bin/quarto preview <file-or-dir> --no-browser --port 4444
# Windows (Git Bash)
source tests/.venv/Scripts/activate
./package/dist/bin/quarto.cmd preview <file-or-dir> --no-browser --port 4444
Use --no-browser to control browser connection. Use --port for a predictable URL.
With debug logging
./package/dist/bin/quarto preview <file> --no-browser --port 4444 --log-level debug 2>&1 | tee preview.log
In background
# Linux/macOS (after venv activation)
./package/dist/bin/quarto preview <file> --no-browser --port 4444 &
PREVIEW_PID=$!
# ... run verification ...
kill $PREVIEW_PID
# Windows (Git Bash, after venv activation)
./package/dist/bin/quarto.cmd preview <file> --no-browser --port 4444 &
PREVIEW_PID=$!
# ... run verification ...
kill $PREVIEW_PID
Edit-Verify Cycle
The core test pattern:
- Start preview with
--no-browser --port 4444 - Use
/agent-browserto navigate tohttp://localhost:4444/and verify content - Edit source file, wait 3-5 seconds for re-render
- Verify content updated in browser
- Check filesystem for unexpected artifacts
- Stop preview, verify cleanup
What to Verify
In browser (via /agent-browser): Page loads, content matches source, updates reflect edits.
In terminal/logs: No BadResource errors, no crashes, preview stays responsive.
On filesystem: No orphaned temp files, cleanup happens on exit.
Windows Limitations
On Windows, kill from Git Bash does not trigger Quarto's onCleanup handler (SIGINT doesn't propagate to Windows processes the same way). Cleanup-on-exit verification requires an interactive terminal with Ctrl+C. For automated testing, verify artifacts during preview instead.
Context Types
Preview behaves differently depending on input:
| Input | Code path |
|---|---|
| Single file (no project) | preview() -> renderForPreview() |
| File within a project | May redirect to project preview via serveProject() |
| Project directory | serveProject() -> watchProject() |
See llm-docs/preview-architecture.md for the full architecture.
When NOT to Use
- Automated smoke tests — use
tests/smoke/instead - Testing render output only (no live preview needed) — use
quarto render - CI environments without browser access
Test Matrix
The full test matrix lives in tests/docs/manual/preview/README.md. Test fixtures live alongside it in tests/docs/manual/preview/.
Running specific tests by ID
When invoked with test IDs (e.g., /quarto-preview-test T17 T18):
- Read
tests/docs/manual/preview/README.md - Find each requested test by its ID (e.g.,
#### T17:) - Parse the Setup, Steps, and Expected fields
- Execute each test following the steps, using the fixtures in
tests/docs/manual/preview/ - Report PASS/FAIL for each test with the actual vs expected result
Running tests by topic
When invoked with a topic description instead of IDs (e.g., /quarto-preview-test root URL or "run preview tests for single-file"):
- Read
tests/docs/manual/preview/README.md - Search test titles and descriptions for matches (keywords, issue numbers, feature area)
- Present the matched tests to the user for confirmation before running:
Found these matching tests: - T17: Single-file preview — root URL accessible (#14298) - T18: Single-file preview — named output URL also accessible Run these? [Y/n] - Only execute after user confirms
Running without arguments
When invoked without test IDs or topic (e.g., /quarto-preview-test), use the general Edit-Verify Cycle workflow described above for ad-hoc preview testing. The test matrix is for targeted regression testing.
Baseline Comparison
Compare dev build against installed release to distinguish regressions:
quarto --version # installed
./package/dist/bin/quarto --version # dev
If both show the same issue, it's pre-existing.