手动测试员技能指南：创建可执行测试脚本与回归测试流程

ln-522-manual-tester by levnikolaevich/claude-code-skills

150 周安装量

253 GitHub Stars

安装命令

npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-522-manual-tester

🇨🇳中文介绍

路径说明： 文件路径（shared/、references/、../ln-*）是相对于技能仓库根目录的。如果在当前工作目录未找到，请定位此 SKILL.md 文件所在的目录并向上返回一级以找到仓库根目录。如果缺少 shared/ 目录，请通过 WebFetch 从 https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path} 获取文件。

输入

输入	必需	来源	描述
`storyId`	是

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1. 快速失败 - 无静默失败

关键： 当任何标准未满足时，测试必须立即返回 1（失败）。

切勿使用： 验证失败时使用 print_status "WARN" + return 0、没有明确标志的优雅降级、隐藏错误的静默回退。

例外情况（允许 WARN）： 不影响正确性的信息性警告、可选功能（在注释中明确说明理由）、基础设施问题（例如，开发环境中缺少 Nginx）。

2. 基于预期的测试 - 黄金标准

关键： 测试必须将实际结果与预期的参考文件进行比较，而不是应用启发式方法或算法检查。

tests/manual/NN-feature/
├── samples/               # 输入文件
├── expected/              # 预期输出文件（必需！）
│   └── {base_name}_{source_lang}-{target_lang}.{ext}
└── test-*.sh

启发式方法仅适用于： 动态/非确定性数据（时间戳、UUID、令牌 - 在比较前进行规范化；具有无序键的 JSON - 使用 jq --sort-keys）。

测试结果保存到 tests/manual/results/（持久化，在 .gitignore 中）。命名方式：result_{ac_name}.{ext} 或 response_{ac_name}.json。测试完成后可检查以进行调试。

4. 预期文件生成

创建预期文件的方法：

使用当前实现运行测试
在 results/ 文件夹中检查输出
如果正确：复制到 expected/ 文件夹并正确命名
如果不正确：首先修复实现，然后复制

重要： 切勿盲目地将结果复制到 expected 文件夹。务必先验证正确性。

阶段 0：解析输入

必读： 加载 shared/references/input_resolution_pattern.md

解析 storyId： 根据指南运行用户故事解析链（状态过滤器：[待评审]）。

阶段 1：设置 tests/manual 结构

阅读 docs/project/infrastructure.md — 获取端口分配、服务端点、基础 URL。阅读 docs/project/runbook.md — 获取 Docker 命令、测试先决条件、环境设置
检查项目根目录中是否存在 tests/manual/ 文件夹
如果缺失，创建结构：
- tests/manual/config.sh — 共享配置（BASE_URL、辅助函数、颜色）
- tests/manual/README.md — 文件夹文档（参见下面的 README.md 模板）
- tests/manual/test-all.sh — 运行所有测试套件的主脚本（参见下面的 test-all.sh 模板）
- tests/manual/results/ — 用于测试输出的文件夹（添加到 .gitignore）
如果不存在，将 tests/manual/results/ 添加到项目 .gitignore 中
如果存在，读取现有的 config.sh 以重用设置（BASE_URL、令牌）

阶段 2：创建用户故事测试脚本

获取用户故事，将验收标准解析为 Given/When/Then 列表（3-5 个预期）
- 检查研究评论（来自 ln-521-test-researcher）— 将发现结果纳入测试用例
检测 API 与 UI（API → curl，UI → puppeteer）。如果是 UI： 必读： 加载 references/puppeteer_patterns.md
创建测试文件夹结构：
- tests/manual/{NN}-{story-slug}/samples/ — 输入文件（如果需要）
- tests/manual/{NN}-{story-slug}/expected/ — 预期输出文件（确定性测试必需）
生成测试脚本：tests/manual/{NN}-{story-slug}/test-{story-slug}.sh
- 使用适当的模板：TEMPLATE-api-endpoint.sh（直接调用）或 TEMPLATE-document-format.sh（异步作业）
- 头部：用户故事 ID、验收标准列表、先决条件
- 每个验收标准 + 边界/错误情况的测试函数
- 基于 diff 的验证，对照预期文件（主要）
- 结果保存到 tests/manual/results/
- 包含时间的摘要表格
使脚本可执行（chmod +x）

阶段 3：更新文档

更新 tests/manual/README.md：
- 在“可用测试套件”表格中添加新测试
- 包含用户故事 ID、覆盖的验收标准、运行命令
更新 tests/manual/test-all.sh：
- 在 SUITES 数组中添加对新脚本的调用
- 保持执行顺序（00-setup 优先，然后是编号的套件）

阶段 4：执行并报告

必读： 加载 references/test_result_format_v1.md

重建 Docker 容器（无缓存），确保健康运行
运行生成的脚本，捕获输出
解析结果（通过/失败计数）
发布 Linear 评论（根据 test_result_format_v1.md），包含：
- 验收标准矩阵（每个验收标准的通过/失败情况）
- 脚本路径：tests/manual/{NN}-{story-slug}/test-{story-slug}.sh
- 重新运行命令：cd tests/manual && ./{NN}-{story-slug}/test-{story-slug}.sh

脚本保存到项目的 tests/manual/，而非临时文件。
测试前重建 Docker；如果重建/运行不健康则失败。
在脚本注释和 Linear 评论中保持用户故事的语言（英文/俄文）。
不进行修复或状态更改；仅提供证据和结论。
脚本必须是幂等的（可随时重新运行）。

tests/manual/ 结构存在（如果缺失则创建 config.sh、README.md、test-all.sh、results/）。
tests/manual/results/ 已添加到项目 .gitignore。
测试脚本已创建于 tests/manual/{NN}-{story-slug}/test-{story-slug}.sh。
已创建 expected/ 文件夹，每个确定性验收标准至少包含 1 个预期文件。
脚本使用基于 diff 的验证对照预期文件（而非启发式方法）。
脚本将结果保存到 tests/manual/results/ 以进行调试。
脚本可执行且幂等。
README.md 已更新，在“可用测试套件”表格中添加了新测试套件。
test-all.sh 已更新，在 SUITES 数组中添加了对新脚本的调用。
应用已重建并运行；测试已执行。
已发布结论和 Linear 评论，包含脚本路径和重新运行命令。

README.md（每个项目创建一次）

# 手动测试脚本

> **范围：** 用于手动 API 测试的 Bash 脚本。通过基于 CLI 的工作流程补充自动化测试。

## 快速开始

```bash
cd tests/manual
./00-setup/create-account.sh  # （如果需要身份验证）
./test-all.sh                 # 运行所有测试套件

Docker 容器正在运行（docker compose ps）
已安装 jq（apt-get install jq 或 brew install jq）

tests/manual/
├── config.sh          # 共享配置（BASE_URL、辅助函数、颜色）
├── README.md          # 此文件
├── test-all.sh        # 运行所有测试套件
├── 00-setup/          # 账户和令牌设置（如果需要身份验证）
│   ├── create-account.sh
│   └── get-token.sh
└── {NN}-{topic}/      # 按用户故事划分的测试套件
    └── test-{slug}.sh

套件	用户故事	覆盖的验收标准	运行命令
—	—	—	—

在 {NN}-{topic}/test-{slug}.sh 中创建脚本
更新此 README（可用测试套件表格）
更新 test-all.sh（添加到 SUITES 数组）

### test-all.sh（每个项目创建一次）

```bash
#!/bin/bash
# =============================================================================
# 运行所有手动测试套件
# =============================================================================
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/config.sh"

echo "=========================================="
echo "运行所有手动测试套件"
echo "=========================================="

check_jq
check_api

# 设置（如果存在）
[ -f "$SCRIPT_DIR/00-setup/create-account.sh" ] && "$SCRIPT_DIR/00-setup/create-account.sh"
[ -f "$SCRIPT_DIR/00-setup/get-token.sh" ] && "$SCRIPT_DIR/00-setup/get-token.sh"

# 测试套件（在此处添加新套件）
SUITES=(
    # "01-auth/test-auth-flow.sh"
    # "02-translation/test-translation.sh"
)

PASSED=0; FAILED=0
for suite in "${SUITES[@]}"; do
    echo ""
    echo "=========================================="
    echo "正在运行：$suite"
    echo "=========================================="
    if "$SCRIPT_DIR/$suite"; then
        ((++PASSED))
        print_status "PASS" "$suite"
    else
        ((++FAILED))
        print_status "FAIL" "$suite"
    fi
done

echo ""
echo "=========================================="
echo "总计：$PASSED 个套件通过，$FAILED 个失败"
echo "=========================================="
[ $FAILED -eq 0 ] && exit 0 || exit 1

config.sh（每个项目创建一次）

#!/bin/bash
# 手动测试脚本的共享配置
export BASE_URL="${BASE_URL:-http://localhost:8080}"
export RED='\033[0;31m'
export GREEN='\033[0;32m'
export YELLOW='\033[1;33m'
export NC='\033[0m'

print_status() {
    local status=$1; local message=$2
    case $status in
        "PASS") echo -e "${GREEN}[PASS]${NC} $message" ;;
        "FAIL") echo -e "${RED}[FAIL]${NC} $message" ;;
        "WARN") echo -e "${YELLOW}[WARN]${NC} $message" ;;
        "INFO") echo -e "[INFO] $message" ;;
    esac
}

check_jq() {
    command -v jq &> /dev/null || { echo "Error: jq required"; exit 1; }
}

check_api() {
    local response=$(curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/health" 2>/dev/null)
    if [ "$response" != "200" ]; then
        echo "Error: API not reachable at $BASE_URL"
        exit 1
    fi
    print_status "INFO" "API reachable at $BASE_URL"
}

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export SCRIPT_DIR

参见： references/templates/

模板	用例	位置
template-api-endpoint.sh	API 端点测试（无异步作业）	template-api-endpoint.sh
template-document-format.sh	文档/文件处理（包含异步作业）	template-document-format.sh

cp references/templates/template-api-endpoint.sh {NN}-feature/test-{feature}.sh      # 端点测试
cp references/templates/template-document-format.sh {NN}-feature/test-{format}.sh    # 文档测试

脚本格式参考：prompsit-api tests/manual/（生产环境示例）
验收标准格式：shared/templates/test_task_template.md（或目标项目中的本地 docs/templates/）
基于风险的上下文：shared/references/risk_based_testing_guide.md
研究发现：ln-521-test-researcher 在用户故事上创建 "## Test Research" 评论
Puppeteer 模式：references/puppeteer_patterns.md
测试结果格式：references/test_result_format_v1.md

版本： 1.0.0 最后更新： 2026-01-15

🇺🇸English

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

Inputs

Input	Required	Source	Description
`storyId`	Yes	args, git branch, kanban, user	Story to process

Resolution: Story Resolution Chain. Status filter: To Review

Manual Tester

Manually verifies Story AC on running code and reports structured results for the quality gate.

Purpose & Scope

Create executable test scripts in tests/manual/ folder of target project.
Run AC-driven checks via bash/curl (API) or puppeteer (UI).
Save scripts permanently for regression testing (not temp files).
Document results in Linear with pass/fail per AC and script path.
No status changes or task creation.

When to Use

Invoked by ln-520-test-planner after ln-521-test-researcher completes
Research comment "## Test Research:" exists on Story (from ln-521)
All implementation tasks in Story status = Done

Test Design Principles

1. Fail-Fast - No Silent Failures

CRITICAL: Tests MUST return 1 (fail) immediately when any criterion is not met.

Never use: print_status "WARN" + return 0 for validation failures, graceful degradation without explicit flags, silent fallbacks that hide errors.

Exceptions (WARN is OK): Informational warnings that don't affect correctness, optional features (with clear justification in comments), infrastructure issues (e.g., missing Nginx in dev environment).

2. Expected-Based Testing - The Golden Standard

CRITICAL: Tests MUST compare actual results against expected reference files , not apply heuristics or algorithmic checks.

Directory structure:

tests/manual/NN-feature/
├── samples/               # Input files
├── expected/              # Expected output files (REQUIRED!)
│   └── {base_name}_{source_lang}-{target_lang}.{ext}
└── test-*.sh

Heuristics acceptable ONLY for: dynamic/non-deterministic data (timestamps, UUIDs, tokens - normalize before comparison; JSON with unordered keys - use jq --sort-keys).

3. Results Storage

Test results saved to tests/manual/results/ (persistent, in .gitignore). Named: result_{ac_name}.{ext} or response_{ac_name}.json. Inspectable after test completion for debugging.

4. Expected File Generation

To create expected files:

Run test with current implementation
Review output in results/ folder
If correct: copy to expected/ folder with proper naming
If incorrect: fix implementation first, then copy

IMPORTANT: Never blindly copy results to expected. Always validate correctness first.

Workflow

Phase 0: Resolve Inputs

MANDATORY READ: Load shared/references/input_resolution_pattern.md

Resolve storyId: Run Story Resolution Chain per guide (status filter: [To Review]).

Phase 1: Setup tests/manual structure

Readdocs/project/infrastructure.md — get port allocation, service endpoints, base URLs. Readdocs/project/runbook.md — get Docker commands, test prerequisites, environment setup
Check if tests/manual/ folder exists in project root
If missing, create structure:
- tests/manual/config.sh — shared configuration (BASE_URL, helpers, colors)
- tests/manual/README.md — folder documentation (see README.md template below)
- tests/manual/test-all.sh — master script to run all test suites (see test-all.sh template below)
- tests/manual/results/ — folder for test outputs (add to .gitignore)

Phase 2: Create Story test script

Fetch Story, parse AC into Given/When/Then list (3-5 expected)
- Check for research comment (from ln-521-test-researcher) — incorporate findings into test cases
Detect API vs UI (API → curl, UI → puppeteer). IF UI: MANDATORY READ: Load references/puppeteer_patterns.md
Create test folder structure:
- tests/manual/{NN}-{story-slug}/samples/ — input files (if needed)
- tests/manual/{NN}-{story-slug}/expected/ — expected output files (REQUIRED for deterministic tests)
Generate test script: tests/manual/{NN}-{story-slug}/test-{story-slug}.sh
- Use appropriate template: TEMPLATE-api-endpoint.sh (direct calls) or TEMPLATE-document-format.sh (async jobs)
- Header: Story ID, AC list, prerequisites
- Test function per AC + edge/error cases
- diff-based validation against expected files (PRIMARY)
- Results saved to tests/manual/results/

Phase 3: Update Documentation

Update tests/manual/README.md:
- Add new test to "Available Test Suites" table
- Include Story ID, AC covered, run command
Update tests/manual/test-all.sh:
- Add call to new script in SUITES array
- Maintain execution order (00-setup first, then numbered suites)

Phase 4: Execute and report

MANDATORY READ: Load references/test_result_format_v1.md

Rebuild Docker containers (no cache), ensure healthy
Run generated script, capture output
Parse results (pass/fail counts)
Post Linear comment (per test_result_format_v1.md) with:
- AC matrix (pass/fail per AC)
- Script path: tests/manual/{NN}-{story-slug}/test-{story-slug}.sh
- Rerun command: cd tests/manual && ./{NN}-{story-slug}/test-{story-slug}.sh

Critical Rules

Scripts saved to project tests/manual/, NOT temp files.
Rebuild Docker before testing; fail if rebuild/run unhealthy.
Keep language of Story (EN/RU) in script comments and Linear comment.
No fixes or status changes; only evidence and verdict.
Script must be idempotent (can rerun anytime).

Definition of Done

tests/manual/ structure exists (config.sh, README.md, test-all.sh, results/ created if missing).
tests/manual/results/ added to project .gitignore.
Test script created at tests/manual/{NN}-{story-slug}/test-{story-slug}.sh.
expected/ folder created with at least 1 expected file per deterministic AC.
Script uses diff-based validation against expected files (not heuristics).
Script saves results to tests/manual/results/ for debugging.
Script is executable and idempotent.
README.md updated with new test suite in "Available Test Suites" table.
test-all.sh updated with call to new script in SUITES array.
App rebuilt and running; tests executed.
Verdict and Linear comment posted with script path and rerun command.

Script Templates

README.md (created once per project)

# Manual Testing Scripts

> **SCOPE:** Bash scripts for manual API testing. Complements automated tests with CLI-based workflows.

## Quick Start

```bash
cd tests/manual
./00-setup/create-account.sh  # (if auth required)
./test-all.sh                 # Run ALL test suites

Prerequisites

Docker containers running (docker compose ps)
jq installed (apt-get install jq or brew install jq)

Folder Structure

tests/manual/
├── config.sh          # Shared configuration (BASE_URL, helpers, colors)
├── README.md          # This file
├── test-all.sh        # Run all test suites
├── 00-setup/          # Account & token setup (if auth required)
│   ├── create-account.sh
│   └── get-token.sh
└── {NN}-{topic}/      # Test suites by Story
    └── test-{slug}.sh

Available Test Suites

Suite	Story	AC Covered	Run Command
—	—	—	—

Adding New Tests

Create script in {NN}-{topic}/test-{slug}.sh
Update this README (Available Test Suites table)
Updatetest-all.sh (add to SUITES array)

### test-all.sh (created once per project)

```bash
#!/bin/bash
# =============================================================================
# Run all manual test suites
# =============================================================================
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/config.sh"

echo "=========================================="
echo "Running ALL Manual Test Suites"
echo "=========================================="

check_jq
check_api

# Setup (if exists)
[ -f "$SCRIPT_DIR/00-setup/create-account.sh" ] && "$SCRIPT_DIR/00-setup/create-account.sh"
[ -f "$SCRIPT_DIR/00-setup/get-token.sh" ] && "$SCRIPT_DIR/00-setup/get-token.sh"

# Test suites (add new suites here)
SUITES=(
    # "01-auth/test-auth-flow.sh"
    # "02-translation/test-translation.sh"
)

PASSED=0; FAILED=0
for suite in "${SUITES[@]}"; do
    echo ""
    echo "=========================================="
    echo "Running: $suite"
    echo "=========================================="
    if "$SCRIPT_DIR/$suite"; then
        ((++PASSED))
        print_status "PASS" "$suite"
    else
        ((++FAILED))
        print_status "FAIL" "$suite"
    fi
done

echo ""
echo "=========================================="
echo "TOTAL: $PASSED suites passed, $FAILED failed"
echo "=========================================="
[ $FAILED -eq 0 ] && exit 0 || exit 1

config.sh (created once per project)

#!/bin/bash
# Shared configuration for manual testing scripts
export BASE_URL="${BASE_URL:-http://localhost:8080}"
export RED='\033[0;31m'
export GREEN='\033[0;32m'
export YELLOW='\033[1;33m'
export NC='\033[0m'

print_status() {
    local status=$1; local message=$2
    case $status in
        "PASS") echo -e "${GREEN}[PASS]${NC} $message" ;;
        "FAIL") echo -e "${RED}[FAIL]${NC} $message" ;;
        "WARN") echo -e "${YELLOW}[WARN]${NC} $message" ;;
        "INFO") echo -e "[INFO] $message" ;;
    esac
}

check_jq() {
    command -v jq &> /dev/null || { echo "Error: jq required"; exit 1; }
}

check_api() {
    local response=$(curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/health" 2>/dev/null)
    if [ "$response" != "200" ]; then
        echo "Error: API not reachable at $BASE_URL"
        exit 1
    fi
    print_status "INFO" "API reachable at $BASE_URL"
}

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export SCRIPT_DIR

Test Script Templates

See: references/templates/

Template	Use Case	Location
template-api-endpoint.sh	API endpoint tests (NO async jobs)	template-api-endpoint.sh
template-document-format.sh	Document/file processing (WITH async jobs)	template-document-format.sh

Quick start:

cp references/templates/template-api-endpoint.sh {NN}-feature/test-{feature}.sh      # Endpoint tests
cp references/templates/template-document-format.sh {NN}-feature/test-{format}.sh    # Document tests

Reference Files

Script format reference: prompsit-api tests/manual/ (production example)
AC format: shared/templates/test_task_template.md (or local docs/templates/ in target project)
Risk-based context: shared/references/risk_based_testing_guide.md
Research findings: ln-521-test-researcher creates "## Test Research" comment on Story
Puppeteer patterns: references/puppeteer_patterns.md
Test result format: references/test_result_format_v1.md

Version: 1.0.0 Last Updated: 2026-01-15

Weekly Installs

150

Repository

levnikolaevich/…e-skills

GitHub Stars

253

First Seen

Feb 11, 2026

Security Audits

Gen Agent Trust HubWarn SocketWarn SnykWarn

Installed on

cursor140

opencode139

codex138

gemini-cli137

github-copilot137

amp135

Skills CLI 使用指南：AI Agent 技能包管理器安装与管理教程

36,300 周安装

Add tests/manual/results/ to project .gitignore if not present

If exists, read existing config.sh to reuse settings (BASE_URL, tokens)

Summary table with timing

Make script executable (chmod +x)

手动测试员技能指南：创建可执行测试脚本与回归测试流程

🇨🇳中文介绍

输入

相关 Skills

手动测试员

目的与范围

使用时机

测试设计原则