Markdown Test Files

Use markdown files when you want deterministic, reusable QA checks for local or CI runs.

Recommended structure

TESTER.md
tests/
  01-landing-page.md
  02-quick-test-runner.md
  03-create-project.md

• Keep shared setup and environment notes in TESTER.md.
• Keep one scenario per file in tests/.
• Use numeric prefixes (01-..., 02-...) for stable order in reviews and logs.

How TESTER.md is applied

• In directory mode (ta run tests/), CLI prepends TESTER.md to every executable markdown test.
• In single-file mode (ta run tests/01-landing-page.md), CLI walks up directories and prepends the nearest TESTER.md.
• In directory mode, CLI runs only top-level *.md files and skips README.md and TESTER.md.

This is useful for shared auth flow, target assumptions, and known environment quirks.

Real example (this repo)

This repository uses:

• TESTER.md in repo root for shared login + environment instructions.
• tests/*.md for scenario-specific checks (landing page, project flows, billing checks, and more).

That lets every test stay short and focused, while shared setup stays centralized.

Example files

TESTER.md

# Shared Test Instructions

Use `<target_url>` as the app under test.

## Authentication

1. Open `<target_url>/sign-in`
2. Sign in as `tester@tester.army`
3. Complete magic link callback flow

## Environment notes

- Minor visual inconsistencies can be expected in staging
- Focus on functional failures for pass/fail

tests/01-landing-page.md

# Landing page loads

Goal: verify public landing page is reachable and key CTA is visible.

Steps:

1. Navigate to `<target_url>/`
2. Confirm page title mentions Tester Army
3. Confirm a primary CTA like "Get Started" or "Sign in" is visible
4. Return pass if all checks succeed; otherwise fail with a short reason

Run commands

# 1) Set target app URL once
export TESTERARMY_TARGET_URL="http://localhost:3000"

# 2) Run one markdown scenario
ta run tests/01-landing-page.md

# 3) Run whole suite (parallel)
ta run tests/ --parallel 3

# 4) CI/machine readable output
ta run tests/ --json --output .testerarmy/latest.json

Authoring guidelines

• Write clear action + assertion steps in plain English.
• Avoid hardcoded domains in test content; use TESTERARMY_TARGET_URL or --url.
• Put only shared instructions in TESTER.md; keep test files focused on scenario intent.
• Prefer many small tests over one long script for easier failure triage.

Related Guides

• TesterArmy CLI for full command/reference docs.
• Quick Test for ad-hoc prompt-first checks in dashboard.