ln-522-manual-tester

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

路径说明： 文件路径（
shared/
、
references/
、
../ln-*
）均相对于技能仓库根目录。如果在当前工作目录找不到，请定位到该SKILL.md所在目录，再向上一级即为仓库根目录。

Manual Tester

手动测试工具

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

在运行的代码上手动验证Story AC，并向质量门禁上报结构化结果。

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.

在目标项目的
```
tests/manual/
```
文件夹下创建可执行测试脚本。
通过bash/curl（API场景）或puppeteer（UI场景）执行AC驱动的校验。
永久保存脚本用于回归测试（不得使用临时文件）。
在Linear中记录测试结果，标注每个AC的通过/失败状态以及脚本路径。
不修改状态或创建新任务。

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

在ln-521-test-researcher完成工作后，由ln-520-test-planner调用
Story上存在来自ln-521的"## Test Research:"调研注释
Story下所有实现任务的状态均为Done

Test Design Principles

测试设计原则

1. Fail-Fast - No Silent Failures

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

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).

核心要求： 当任何条件不满足时，测试必须立即返回1（失败）。

禁止使用： 校验失败时使用

print_status "WARN" + return 0

、无显式标记的优雅降级、隐藏错误的静默降级逻辑。

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

2. Expected-Based Testing - The Golden Standard

2. 基于预期值测试 - 黄金准则

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

核心要求： 测试必须将实际结果与预期参考文件对比，不得使用启发式或算法校验。

目录结构：

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

仅以下场景允许使用启发式校验： 动态/非确定性数据（时间戳、UUID、token - 对比前先做标准化；键顺序无序的JSON - 使用

jq --sort-keys

处理）。

3. Results Storage

3. 结果存储

Test results saved to

tests/manual/results/

(persistent, in .gitignore). Named:

result_{ac_name}.{ext}

response_{ac_name}.json

. Inspectable after test completion for debugging.

测试结果保存在

tests/manual/results/

目录下（持久化存储，加入.gitignore），命名规则为：

result_{ac_name}.{ext}

或

response_{ac_name}.json

，测试完成后可查看结果用于调试。

4. Expected File Generation

4. 预期文件生成

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.

创建预期文件的步骤：

基于当前实现运行测试
检查
```
results/
```
文件夹下的输出
如果结果正确：按照规范命名后复制到
```
expected/
```
文件夹
如果结果错误：先修复实现，再复制

重要提示： 切勿盲目将结果复制到预期文件夹，必须先验证结果的正确性。

Workflow

工作流程

Phase 1: Setup tests/manual structure

阶段1：搭建tests/manual目录结构

Read
docs/project/runbook.md
— get Docker commands, API base URL, 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
```
  )
Add
```
tests/manual/results/
```
to project
```
.gitignore
```
if not present
If exists, read existing
```
config.sh
```
to reuse settings (BASE_URL, tokens)

阅读
docs/project/runbook.md
— 获取Docker命令、API基础地址、测试前置条件、环境配置说明
检查项目根目录下是否存在
```
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、token）

Phase 2: Create Story test script

阶段2：创建Story测试脚本

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)
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/
```
- Summary table with timing
Make script executable (
```
chmod +x
```
)

拉取Story，将AC拆解为Given/When/Then列表（3-5个预期结果）
- 检查调研注释（来自ln-521-test-researcher）— 将调研结论纳入测试用例
区分测试类型是API还是UI（API用curl，UI用puppeteer）
创建测试目录结构：
- ```
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（异步任务场景）
- 头部信息：Story ID、AC列表、前置条件
- 每个AC对应一个测试函数 + 边界/错误场景
- 基于diff对比预期文件的校验方式（主要校验方式）
- 结果保存到
```
tests/manual/results/
```
- 带耗时统计的汇总表格
给脚本添加可执行权限（
```
chmod +x
```
）

Phase 3: Update Documentation

阶段3：更新文档

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)

更新
```
tests/manual/README.md
```
：
- 在"可用测试套件"表格中新增本次测试
- 包含Story ID、覆盖的AC、运行命令
更新
```
tests/manual/test-all.sh
```
：
- 在SUITES数组中添加对新脚本的调用
- 保持执行顺序（00-setup优先，之后按编号顺序执行）

Phase 4: Execute and report

阶段4：执行测试并上报结果

Rebuild Docker containers (no cache), ensure healthy
Run generated script, capture output
Parse results (pass/fail counts)

Post Linear comment 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

无缓存重建Docker容器，确保容器健康
运行生成的脚本，捕获输出
解析结果（通过/失败统计）

在Linear中发布评论，包含：

AC矩阵（每个AC的通过/失败状态）

脚本路径：

tests/manual/{NN}-{story-slug}/test-{story-slug}.sh

重跑命令：

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).

脚本保存在项目
```
tests/manual/
```
目录下，不得使用临时文件。
测试前重建Docker；如果重建/运行不健康则测试失败。
脚本注释和Linear评论保留Story的原始语言（英文/俄文）。
不做代码修复或状态修改，仅提供证据和结论。
脚本必须是幂等的（可随时重复运行）。

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.

```
tests/manual/
```
结构完整（如缺失则创建config.sh、README.md、test-all.sh、results/）。
```
tests/manual/results/
```
已加入项目
```
.gitignore
```
。

测试脚本已创建在

tests/manual/{NN}-{story-slug}/test-{story-slug}.sh

路径下。

```
expected/
```
文件夹已创建，每个确定性AC至少对应1个预期文件。
脚本使用基于diff对比预期文件的校验方式（非启发式校验）。
脚本将结果保存到
```
tests/manual/results/
```
用于调试。
脚本具备可执行权限且是幂等的。
README.md已更新，在"可用测试套件"表格中新增了本次测试套件。
test-all.sh已更新，在SUITES数组中添加了对新脚本的调用。
应用已重建并运行；测试已执行。
已发布Linear评论，包含测试结论、脚本路径和重跑命令。

Script Templates

脚本模板

README.md (created once per project)

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

markdown

undefined

markdown

undefined

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

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
```
)

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

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
—	—	—	—

Suite	Story	AC Covered	Run Command
—	—	—	—

Adding New Tests

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

undefined

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

undefined

test-all.sh (created once per project)

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

bash

#!/bin/bash

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

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

undefined

SUITES=( # "01-auth/test-auth-flow.sh" # "02-translation/test-translation.sh" )

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

undefined

config.sh (created once per project)

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

bash

#!/bin/bash

bash

#!/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

undefined

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'

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

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

undefined

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:

bash

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

查看： references/templates/

模板	适用场景	位置
template-api-endpoint.sh	API端点测试（无异步任务）	template-api-endpoint.sh
template-document-format.sh	文档/文件处理（含异步任务）	template-document-format.sh

快速开始：

bash

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

Version: 1.0.0 Last Updated: 2026-01-15

脚本格式参考：prompsit-api
```
tests/manual/
```
（生产环境示例）

AC格式：

shared/templates/test_task_template.md

（或目标项目本地的

docs/templates/

）

基于风险的测试上下文：

shared/references/risk_based_testing_guide.md

调研结论：ln-521-test-researcher在Story上创建的"## Test Research"注释

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