run-uat

name	run-uat
description	Run User Acceptance Testing by creating a PR with rendered markdown on GitHub or Azure DevOps. Use when validating markdown rendering in real platforms.
compatibility	Requires git. GitHub UAT uses repo scripts which require GitHub CLI (gh) authenticated. Azure DevOps UAT requires Azure CLI (az) + azure-devops extension. Network access required.

Run UAT

Purpose

Execute end-to-end User Acceptance Testing by posting the comprehensive demo artifact to a real PR comment on GitHub or Azure DevOps, then validating the rendered output.

Hard Rules

Must

• Generate fresh artifacts before posting (use generate-demo-artifacts skill).
• Create a unique UAT branch to avoid collisions.
• Default to the comprehensive demo artifact when there are no special requirements.
• Clean up (close/abandon) the UAT PR after testing.
• Report platform-specific rendering issues clearly.

Must Not

• Post a minimal or simulation artifact (reject files containing "minimal" or "simulation" in the name).
• Leave UAT PRs open after testing completes.
• Modify any source code during UAT.

Pre-requisites

• GitHub UAT: repo scripts require GitHub CLI (gh) authenticated.
• Azure DevOps UAT: Azure CLI (az) with DevOps extension.

For read-only inspection of PR state/comments during UAT (outside the scripts), prefer GitHub chat tools when available.

Actions

Recommended: Single Wrapper Command

This repository provides a stable wrapper that creates UAT PR(s), polls for approval, and cleans up in one command.

# Default artifact selection:
# - GitHub: $UAT_ARTIFACT_GITHUB (fallback: artifacts/comprehensive-demo.md)
# - AzDO:   $UAT_ARTIFACT_AZDO   (fallback: artifacts/comprehensive-demo.md)
scripts/uat-run.sh

If a feature requires a different report (e.g., summary-only, custom template tests), pass the artifact explicitly:

scripts/uat-run.sh artifacts/<feature-specific-report>.md

If you need to target only one platform:

scripts/uat-run.sh --platform github
scripts/uat-run.sh --platform azdo

# Or with an explicit artifact override for a feature-specific UAT:
scripts/uat-run.sh artifacts/<feature-specific-report>.md --platform github
scripts/uat-run.sh artifacts/<feature-specific-report>.md --platform azdo

0. Recommended: Rebase on Latest Main

Before running UAT, ensure your branch is up to date to avoid testing against stale base changes. Use the git-rebase-main skill.

1. Create UAT Branch

# Generate unique branch name
original_branch=$(git branch --show-current)
timestamp=$(date -u +%Y%m%d%H%M%S)
uat_branch="${original_branch}-uat-${timestamp}"

# Create and switch to UAT branch
git checkout -b "$uat_branch"

2. Generate Fresh Artifacts

Use the generate-demo-artifacts skill to ensure the artifact is current.

3. Validate Artifact

artifact="artifacts/comprehensive-demo.md"

# Reject known bad artifacts
if echo "$artifact" | grep -qiE '(minimal|simulation)'; then
  echo "ERROR: Refusing to use a minimal/simulation artifact for UAT."
  exit 1
fi

# Verify file exists and is substantial
if [[ ! -s "$artifact" ]] || [[ $(wc -l < "$artifact") -lt 50 ]]; then
  echo "ERROR: Artifact is missing or too small. Generate it first."
  exit 1
fi

echo "Artifact validated: $artifact ($(wc -l < "$artifact") lines)"

4. Run UAT on GitHub

scripts/uat-github.sh create "$artifact"
# Note the PR number from output

# Poll for rendering and approval
scripts/uat-github.sh poll <pr-number>

# After validation, cleanup
scripts/uat-github.sh cleanup <pr-number>

5. Run UAT on Azure DevOps

# Setup (first time only)
scripts/uat-azdo.sh setup

# Create PR and post artifact
scripts/uat-azdo.sh create "$artifact"
# Note the PR ID from output

# Poll for rendering and approval
scripts/uat-azdo.sh poll <pr-id>

# After validation, cleanup
scripts/uat-azdo.sh cleanup <pr-id>

6. Return to Original Branch

git checkout "$original_branch"

Golden Example

$ scripts/uat-github.sh create artifacts/comprehensive-demo.md
[INFO] Pushing branch to GitHub...
[INFO] Creating PR...
PR created: #42
[INFO] Posted comprehensive-demo.md as comment on PR #42

$ scripts/uat-github.sh poll 42
[INFO] Checking PR #42 for new comments...
[INFO] Found 1 new comment(s). Waiting for approval...

$ scripts/uat-github.sh cleanup 42
[INFO] Closing PR #42...
[INFO] UAT complete.

Troubleshooting

Issue	Solution
"Refusing to use minimal artifact"	Run generate-demo-artifacts skill first
"Branch already exists"	Delete old UAT branch: git branch -D <branch>
"gh: command not found"	Install GitHub CLI: brew install gh or apt install gh
Azure DevOps auth fails	Run az login and scripts/uat-azdo.sh setup