Doc Tester

# Start Aspire in background (won't be interrupted by other commands)
cd /path/to/hex1b
nohup aspire run > /tmp/aspire.log 2>&1 &

# Wait a few seconds for startup, then check logs
sleep 10 && head -15 /tmp/aspire.log

# Call the MCP tool
mcp_aspire_list_resources

# Look for the content resource endpoint_urls
# Example output: http://content-hex1b.dev.localhost:1189

# Run the build-local-package script in this skill directory
./.github/skills/doc-tester/build-local-package.sh

/                           # Landing page with feature overview
/guide/getting-started      # Getting started tutorial
/guide/first-app           # Quick start guide
/guide/widgets-and-nodes   # Core architecture concepts
/guide/layout              # Layout system
/guide/input               # Input handling
/guide/testing             # Testing guide
/guide/theming             # Theming system
/guide/widgets/            # Per-widget documentation
    text
    button
    textbox
    list
    stacks
    containers
    navigator
    ...
/deep-dives/               # Advanced topics
    reconciliation
    ...
/api/                      # API reference
/gallery                   # Examples showcase

# Take an accessibility snapshot to read page content
mcp_playwright_browser_snapshot

# Navigate to a page
mcp_playwright_browser_click with element="Getting Started link"

# Read interactive demos
mcp_playwright_browser_snapshot

# Create test project in the workspace (not /tmp!)
cd /path/to/hex1b
mkdir -p .doc-tester-workspace
cd .doc-tester-workspace
dotnet new console -n DocTest --force
cp ../.doc-tester-packages/NuGet.config DocTest/
cd DocTest
dotnet add package Hex1b --version 1.0.0-local.XXXXXX

# Paste the code example into Program.cs and build
dotnet build

# 1. Activate terminal tools
activate_terminal_session_control_tools
activate_terminal_interaction_tools

# 2. Start an interactive bash shell (use start_pwsh_terminal on Windows)
mcp_terminal-mcp_start_bash_terminal workingDirectory="/path/to/hex1b"

# 3. Wait for shell prompt
mcp_terminal-mcp_wait_for_terminal_text text="$" timeoutSeconds=5

# 4. Navigate to the test project
mcp_terminal-mcp_send_terminal_input text="cd .doc-tester-workspace/DocTest"
mcp_terminal-mcp_send_terminal_key key="Enter"
mcp_terminal-mcp_wait_for_terminal_text text="$" timeoutSeconds=5

# 5. Run the TUI application
mcp_terminal-mcp_send_terminal_input text="dotnet run"
mcp_terminal-mcp_send_terminal_key key="Enter"

# 6. Wait for the TUI to render
mcp_terminal-mcp_wait_for_terminal_text text="Expected UI text" timeoutSeconds=15

# 7. Capture and verify the visual output (ALWAYS use both)
mcp_terminal-mcp_capture_terminal_text      # For text-based verification
mcp_terminal-mcp_capture_terminal_screenshot savePath="/path/to/hex1b/.doc-tester-workspace/screenshots/test-name-step1.svg"

# 8. Interact with the TUI (type, navigate, etc.)
mcp_terminal-mcp_send_terminal_input text="Hello"
mcp_terminal-mcp_send_terminal_key key="Tab"
mcp_terminal-mcp_send_terminal_key key="Enter"

# 9. Verify the result after interaction (ALWAYS use both)
mcp_terminal-mcp_capture_terminal_text      # Text verification
mcp_terminal-mcp_capture_terminal_screenshot savePath="/path/to/hex1b/.doc-tester-workspace/screenshots/test-name-step2.svg"

# 10. Exit the TUI (Ctrl+C) and clean up
mcp_terminal-mcp_send_terminal_key key="c" modifiers=["Ctrl"]
mcp_terminal-mcp_stop_terminal sessionId="..."
mcp_terminal-mcp_remove_session sessionId="..."

# Click the demo button
mcp_playwright_browser_click with element="Run in browser"

# Wait for terminal to appear
mcp_playwright_browser_wait_for with text="..." 

# Take snapshot to see the demo
mcp_playwright_browser_snapshot

# Interact with the demo
mcp_playwright_browser_type with text="test input"
mcp_playwright_browser_press with key="Tab"
mcp_playwright_browser_press with key="Enter"

# Snapshot again to see results
mcp_playwright_browser_snapshot

## Widget: [WidgetName]

### Page: /guide/widgets/[widget-name]

#### Navigation (Playwright)
- [ ] Page loads successfully
- [ ] All sections visible in snapshot
- [ ] Code examples readable

#### Content Clarity
- [ ] Widget purpose is clear
- [ ] When to use this widget is explained
- [ ] Basic usage example is complete and runnable

#### Code Example Testing
- [ ] Example 1: Compiles and runs as described
- [ ] Example 2: Compiles and runs as described
- [ ] (etc.)

#### Live Demo Testing (Playwright)
- [ ] **"Run in browser" button exists** for at least one code example
- [ ] Demo loads when clicked (no 500 errors)
- [ ] Initial state matches description
- [ ] Interactions work as documented
- [ ] Demo matches the code example shown

⚠️ **CRITICAL: If "Run in browser" button is MISSING for interactive widgets, report this as a Critical bug.** Every interactive widget (buttons, inputs, lists, etc.) MUST have at least one working interactive demo. Missing demos indicate incomplete documentation.

#### Cross-Reference
- [ ] Matches `src/Hex1b/Widgets/[WidgetName]Widget.cs`
- [ ] Matches `src/Hex1b/Nodes/[WidgetName]Node.cs`
- [ ] Extension methods accurate
- [ ] Theme elements documented

## Guide: [Page Title]

### Page: /guide/[page-name]

#### Content Verification
- [ ] Conceptual explanations accurate
- [ ] Terminology consistent with codebase
- [ ] Architecture diagrams current
- [ ] Example code compiles

#### Code Examples
For each example:
- [ ] Example [N]: Compiles successfully
- [ ] Example [N]: Runs as described
- [ ] Example [N]: Output matches documentation

#### Links
- [ ] All internal links work
- [ ] External links accessible
- [ ] "Next Steps" links valid

## API: [Type/Namespace]

### Page: /api/[path]

#### Completeness
- [ ] All public types documented
- [ ] All public members documented
- [ ] Parameter descriptions accurate
- [ ] Return value descriptions accurate

#### Accuracy
- [ ] Type signatures match source
- [ ] Default values documented correctly
- [ ] Exceptions documented
- [ ] Examples work as shown

# Documentation Test Report

**Focus Area:** [Description]
**Date:** [ISO Date]
**Tester:** doc-tester agent

## Summary

| Category | Passed | Failed | Warnings |
|----------|--------|--------|----------|
| Content Accuracy | X | Y | Z |
| Code Examples | X | Y | Z |
| Interactive Demos | X | Y | Z |
| Links | X | Y | Z |

## Critical Issues

Issues that make documentation misleading or incorrect.

### Issue 1: [Brief Title]

**Location:** [Page URL and section]
**Type:** [Content/Example/Demo/Link]
**Severity:** Critical

**What the documentation says:**
> [Quote from documentation]

**What actually happens:**
> [Description of actual behavior]

**Evidence:**
[Code snippet, error message, or screenshot description]

**Recommended Action:**
- [ ] Update documentation to match behavior
- [ ] Fix implementation to match documentation
- [ ] Add clarifying note

---

## Warnings

Issues that may confuse readers but aren't strictly incorrect.

### Warning 1: [Brief Title]

**Location:** [Page URL and section]
**Issue:** [Description]
**Suggestion:** [How to improve]

---

## Passed Checks

[List of items that passed validation - brief summary]

## Recommendations

1. **Priority fixes:** [List critical issues to address first]
2. **Documentation gaps:** [Missing documentation to add]
3. **Product issues:** [Implementation bugs discovered]

./.github/skills/doc-tester/build-local-package.sh

✓ Built Hex1b 0.35.0-local.20260105120000
✓ Package: /path/to/hex1b/.doc-tester-packages/Hex1b.0.35.0-local.20260105120000.nupkg
✓ NuGet config: /path/to/hex1b/.doc-tester-packages/NuGet.config

# Navigate to the hex1b repo root
cd /path/to/hex1b

# Create test project directory (name it descriptively for the test)
mkdir -p .doc-tester-workspace/DocTest
cd .doc-tester-workspace/DocTest

# Create new console project
dotnet new console --force

# Copy the local NuGet.config (contains absolute path to packages)
cp ../../.doc-tester-packages/NuGet.config .

# Add the local Hex1b package (use version from build script output)
# The NuGet.config uses an absolute path, so no need to copy the .nupkg file
dotnet add package Hex1b --version 1.0.0-local.20260105120000

# Replace Program.cs with the documentation code sample
cat > Program.cs << 'EOF'
// Paste code example from documentation here
EOF

# Build to verify it compiles
dotnet build

# Start an interactive shell (use start_pwsh_terminal on Windows)
start_bash_terminal workingDirectory="/path/to/hex1b"

# Wait for shell prompt
wait_for_terminal_text text="$" timeoutSeconds=5

# Navigate to test project and run
send_terminal_input text="cd .doc-tester-workspace/DocTest && dotnet run\n"

# Wait for the TUI to render
wait_for_terminal_text text="Expected text" timeoutSeconds=10

# Capture and verify output (ALWAYS use both for TUI apps)
capture_terminal_text      # Text-based verification
capture_terminal_screenshot savePath="/path/to/hex1b/.doc-tester-workspace/screenshots/example-name.svg"

# Interact with the TUI if needed
send_terminal_key key="Tab"
send_terminal_input text="test"

# Exit the TUI (Ctrl+C or Escape depending on the app)
send_terminal_key key="Escape"

# Clean up the session
remove_session sessionId="..."

#!/bin/bash
# test-examples.sh

REPO_ROOT="$(cd "$(dirname "$0")" && pwd)"
EXAMPLES_DIR="$1"
PACKAGE_VERSION="$2"
NUGET_CONFIG="$REPO_ROOT/.doc-tester-packages/NuGet.config"
WORKSPACE="$REPO_ROOT/.doc-tester-workspace"

# Ensure workspace exists
mkdir -p "$WORKSPACE"

for example in "$EXAMPLES_DIR"/*.cs; do
    name=$(basename "$example" .cs)
    test_dir="$WORKSPACE/test-$name"
    
    echo "Testing: $name"
    
    # Clean up any previous test
    rm -rf "$test_dir"
    mkdir -p "$test_dir"
    cd "$test_dir"
    
    dotnet new console --force > /dev/null
    cp "$NUGET_CONFIG" .
    dotnet add package Hex1b --version "$PACKAGE_VERSION" > /dev/null 2>&1
    cp "$example" Program.cs
    
    if dotnet build > /dev/null 2>&1; then
        echo "  ✓ $name: Compiles"
    else
        echo "  ✗ $name: Build failed"
    fi
done

echo "Test projects preserved in $WORKSPACE for inspection"

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="doc-tester-local" value="/absolute/path/to/hex1b/.doc-tester-packages" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="doc-tester-local">
      <package pattern="Hex1b" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

# Remove local packages
rm -rf .doc-tester-packages/

# Or run the build script with --clean
./.github/skills/doc-tester/build-local-package.sh --clean

aspire run

# List all resources and their status
list_resources

# Expected output includes:
# - content (ViteApp) → http://localhost:1189
# - website (CSharpApp) → http://localhost:XXXXX

# 1. Start environment
aspire run

# 2. Build local packages (in another terminal)
./.github/skills/doc-tester/build-local-package.sh

# 3. Use MCP tools to get content URL
# list_resources → find content endpoint

# 4. Fetch pages and test
# fetch_webpage with local URLs

# 5. Test code examples
# Create temp projects with local packages

# 6. Check for errors
# list_console_logs for website resource

list_resources