@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.0

package/docs/templates/backend-test-analysis.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tea-agent.dev/schemas/backend-test-analysis-v1.json",
+  "title": "Backend Test Analysis v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "sourceBinding", "acceptanceCriteria", "endpoints", "dataModels", "businessRules", "stateTransitions", "boundaryConstraints", "externalDependencies", "risks", "evidenceGaps"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "sourceBinding": {
+      "type": "object", "additionalProperties": false,
+      "required": ["taskId", "requirementPath", "requirementSha256", "referencePaths", "requirementIds"],
+      "properties": {
+        "taskId": { "type": "string", "minLength": 1 },
+        "requirementPath": { "type": "string", "minLength": 1 },
+        "requirementSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "referencePaths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "requirementIds": { "type": "array", "items": { "type": "string", "pattern": "^(REQ|BR|AC)-[A-Z0-9]+(-[A-Z0-9]+)*$" } }
+      }
+    },
+    "acceptanceCriteria": { "type": "array", "items": { "$ref": "#/$defs/acceptanceCriterion" } },
+    "endpoints": { "type": "array", "items": { "$ref": "#/$defs/endpoint" } },
+    "dataModels": { "type": "array", "items": { "$ref": "#/$defs/evidencedDescription" } },
+    "businessRules": { "type": "array", "items": { "$ref": "#/$defs/businessRule" } },
+    "stateTransitions": { "type": "array", "items": { "$ref": "#/$defs/stateTransition" } },
+    "boundaryConstraints": { "type": "array", "items": { "$ref": "#/$defs/boundaryConstraint" } },
+    "externalDependencies": { "type": "array", "items": { "$ref": "#/$defs/optionalEvidenceDescription" } },
+    "risks": { "type": "array", "items": { "$ref": "#/$defs/optionalEvidenceDescription" } },
+    "evidenceGaps": { "type": "array", "items": { "$ref": "#/$defs/evidenceGap" } }
+  },
+  "$defs": {
+    "sourceRef": { "type": "string", "minLength": 1 },
+    "field": { "type": "object", "additionalProperties": false, "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "description": { "type": "string" } } },
+    "errorCase": { "type": "object", "additionalProperties": false, "required": ["description"], "properties": { "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "type": "string", "minLength": 1 }, "messageField": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 } } },
+    "acceptanceCriterion": { "type": "object", "additionalProperties": false, "required": ["id", "text", "sourceRef"], "properties": { "id": { "type": "string", "pattern": "^AC-[A-Z0-9]+(-[A-Z0-9]+)*$" }, "text": { "type": "string", "minLength": 1 }, "sourceRef": { "$ref": "#/$defs/sourceRef" } } },
+    "endpoint": { "type": "object", "additionalProperties": false, "required": ["id", "method", "path", "requestFields", "responseFields", "successStatuses", "errorCases"], "properties": { "id": { "type": "string", "minLength": 1 }, "method": { "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] }, "path": { "type": "string", "pattern": "^/" }, "requestFields": { "type": "array", "items": { "$ref": "#/$defs/field" } }, "responseFields": { "type": "array", "items": { "$ref": "#/$defs/field" } }, "successStatuses": { "type": "array", "items": { "type": "integer", "minimum": 100, "maximum": 399 } }, "errorCases": { "type": "array", "items": { "$ref": "#/$defs/errorCase" } } } },
+    "evidencedDescription": { "type": "object", "additionalProperties": false, "required": ["id", "description", "sourceRef"], "properties": { "id": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "sourceRef": { "$ref": "#/$defs/sourceRef" } } },
+    "businessRule": { "type": "object", "additionalProperties": false, "required": ["id", "text", "sourceRef"], "properties": { "id": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1 }, "sourceRef": { "$ref": "#/$defs/sourceRef" } } },
+    "stateTransition": { "type": "object", "additionalProperties": false, "required": ["from", "to", "trigger", "sourceRef"], "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "trigger": { "type": "string", "minLength": 1 }, "sourceRef": { "$ref": "#/$defs/sourceRef" } } },
+    "boundaryConstraint": { "type": "object", "additionalProperties": false, "required": ["field", "constraint", "sourceRef"], "properties": { "field": { "type": "string", "minLength": 1 }, "constraint": { "type": "string", "minLength": 1 }, "sourceRef": { "$ref": "#/$defs/sourceRef" } } },
+    "optionalEvidenceDescription": { "type": "object", "additionalProperties": false, "required": ["description"], "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "sourceRef": { "$ref": "#/$defs/sourceRef" } } },
+    "evidenceGap": { "type": "object", "additionalProperties": false, "required": ["description"], "properties": { "description": { "type": "string", "minLength": 1 }, "requirementId": { "type": "string" }, "sourceRef": { "$ref": "#/$defs/sourceRef" } } }
+  }
+}

package/docs/templates/backend-test-dag.generate-pytest.prompt.md

@@ -1,139 +1,202 @@
-# Backend Test DAG Generate Pytest Prompt Template
-
-## Purpose
-
-Use this prompt for a **pytest code generation** node: `executor: "pi"`, `role: "implementer"`, `toolProfile: "write"`, `writePolicy: "exclusive"`. The implementer converts reviewed backend functional test cases into pytest automation code with 1:1 traceability.
-
-Do **not** create a new executor type. This is a standard `executor: pi` writer node.
-
-## Recommended DAG Node Shape
-
-```json
-{
-  "id": "generate-backend-pytest-pi",
-  "depends_on": ["review-backend-cases-gate-shell"],
-  "complexity": "HIGH",
-  "executor": "pi",
-  "role": "implementer",
-  "toolProfile": "write",
-  "writePolicy": "exclusive",
-  "writeSet": ["testcase/**/test_*.py"],
-  "allowedPaths": ["testcase/**/test_*.py"],
-  "forbiddenPaths": [".harness/**", "artifacts/**"],
-  "outputContract": "Pytest test files under tests/backend/ with 1:1 mapping to functional test case IDs. Summary lists generated files, test function count, and any skipped cases with reasons.",
-  "subtask_prompt_markdown": "./backend-test-dag.generate-pytest.prompt.md"
-}
-```
-
-## Prompt Body
-
-You are the Backend Test DAG **pytest code generator**.
-
-Your job is to convert reviewed test cases under `testcase/md/` into pytest automation code. Write test files under `testcase/` only. Stay within `writeSet`. Do not write root `artifacts/**`.
-
-### Output Steps (do in order)
-
-1. First, output a brief summary: how many files, how many test functions planned
-2. Then write each test file under `testcase/`
-
-### Inputs
-
-1. **Reviewed test cases** — files under `testcase/md/` (approved by `review-backend-cases-pi`).
-2. **Target project conventions** — read `conftest.py`, `pytest.ini` / `pyproject.toml` to understand conventions, but do NOT modify them.
-
-Do NOT re-read source documents. Use the reviewed cases only.
-
-### Conversion Rules
-
-#### File Naming
-
-- Every test file must start with `test_` prefix (e.g. `test_order.py`, `test_user_api.py`)
-- pytest collects tests from files matching `test_*.py` or `*_test.py` — use `test_` prefix exclusively
-- Never create test files without the `test_` prefix
-
-#### Write Boundary
-
-- Only **create new** test script files under `testcase/`
-- Do NOT modify existing files: `conftest.py`, `pytest.ini`, `pyproject.toml`, `setup.cfg`, `__init__.py`, or any other framework/config file
-- Reuse existing fixtures; if required fixtures do not exist, report the gap instead of creating or modifying framework files
-- Read existing framework files to understand conventions, but treat them as immutable
-
-#### Naming Conflict Resolution
-
-- If a file with the target name already exists under `testcase/`, add a numeric suffix: `test_order.py` → `test_order_01.py` → `test_order_02.py`
-- Never overwrite or append to existing files — each test script must be a standalone file
-- Check for existing files before writing; if `test_<module>.py` exists, use `test_<module>_01.py`
-
-#### 1:1 Traceability
-
-Every functional test case ID (`BE-<MODULE>-<NNN>`) must map to exactly one pytest function:
-
-```python
-# testcase/md/BE-ORDER-001 → testcase/test_order.py
-def test_BE_ORDER_001_create_order_with_valid_data():
-    """BE-ORDER-001: Create order with valid request body."""
-    ...
-```
-
-- Function name: `test_<CASE_ID_with_underscores>` (e.g. `test_BE_ORDER_001_...`)
-- Docstring first line: `<CASE_ID>: <Case Title>`
-
-#### File Organization
-
-- All test files go under `testcase/` directory in the host project root
-- Group test files by MODULE segment: `BE-ORDER-*` → `testcase/test_order.py`, `BE-USER-*` → `testcase/test_user.py`
-- Follow existing project conventions for import style, fixture scope
-
-#### Fixture Strategy
-
-- Reuse existing project fixtures from `conftest.py` when available
-- Do not create or modify fixture/configuration files in this node
-- Prefer `@pytest.fixture(scope="function")` for test isolation
-- Use `@pytest.mark.parametrize` for boundary condition cases with multiple inputs
-
-#### Test Integrity
-
-- Tests verify implementation correctness — if a test fails, the implementation likely has a bug, not the test
-- Do NOT weaken assertions, remove test cases, or modify test logic to make tests pass
-- Do NOT add workarounds, skips, or try/except blocks to hide failures without explicit justification
-- Report all failures honestly in the output; the downstream `execute-backend-pytest-shell` node captures exit codes and stdout/stderr as-is
-
-#### Assertions
-
-- Use `assert` statements, not `unittest` assertions
-- Assert specific values, not just "no exception"
-- For API tests: assert status code, response body keys, and specific field values
-- For database tests: assert record state after operation
-
-#### Conditional Test Implementation (include ONLY if test cases exist)
-
-- **Authentication tests**: implement ONLY if `testcase/md/` contains auth-related cases
-  - Use `@pytest.mark.auth` marker
-  - Test no token, expired token, invalid token, insufficient permissions, cross-user access
-- **Timeout tests**: implement ONLY if `testcase/md/` contains timeout-related cases
-  - Use `@pytest.mark.timeout` marker
-  - Use `unittest.mock.patch` or `pytest-mock` to simulate slow responses
-- If no such cases exist in the reviewed test cases, do NOT add these tests
-
-#### Markers
-
-- `@pytest.mark.positive` — happy path cases
-- `@pytest.mark.negative` — error/exception cases
-- `@pytest.mark.boundary` — edge cases
-- `@pytest.mark.<MODULE>` — module-specific marker (e.g. `@pytest.mark.order`)
-
-#### Skip Policy
-
-If a test case cannot be automated (requires external service not mockable, requires manual verification), add it with `@pytest.mark.skip(reason="...")` and document the reason. Do not omit the function — traceability requires it exists.
-
-### Output Shape (after summary line)
-
-After the mandatory summary line, provide:
-
-1. **Generated Files** — list of files written under `tests/backend/`.
-2. **Function Mapping Table** — `| Test Case ID | Pytest Function | File | Marker |`.
-3. **Skipped Cases** — if any, list with reason.
-4. **Conventions Observed** — note project fixtures/config discovered and followed.
-5. **Residual Risks** — cases that may need manual verification or environment setup.
-
-Do not include chain-of-thought. Do not write root `artifacts/**`.
+# Backend Test DAG Generate Pytest Prompt Template
+
+## Purpose
+
+Use this prompt for a **pytest code generation** node: `executor: "pi"`, `role: "implementer"`, `toolProfile: "write"`, `writePolicy: "exclusive"`. The implementer converts reviewed backend functional test cases into pytest automation code with 1:1 traceability.
+
+Do **not** create a new executor type. This is a standard `executor: pi` writer node.
+
+## Recommended DAG Node Shape
+
+```json
+{
+  "id": "generate-backend-pytest-pi",
+  "depends_on": ["review-backend-cases-gate-shell"],
+  "complexity": "HIGH",
+  "executor": "pi",
+  "role": "implementer",
+  "toolProfile": "write",
+  "writePolicy": "exclusive",
+  "writeSet": ["testcase/**/test_*.py", "testcase/**/helpers/**", "testcase/**/factories/**"],
+  "allowedPaths": ["**"],
+  "forbiddenPaths": [".harness/**", "artifacts/**"],
+  "outputContract": "Pytest test files under testcase/ with 1:1 mapping to functional test case IDs; optional helpers/factories. Summary lists generated files, test function count, and any skipped cases with reasons.",
+  "subtask_prompt_markdown": "./backend-test-dag.generate-pytest.prompt.md"
+}
+```
+
+## Prompt Body
+
+You are the Backend Test DAG **pytest code generator**.
+
+Your job is to convert reviewed test cases under `testcase/md/` into pytest automation code. Write test files under `testcase/` only. Stay within `writeSet`. Do not write root `artifacts/**`.
+
+### Output Steps (do in order)
+
+1. First, output a brief summary: how many files, how many test functions planned
+2. Then write each test file under `testcase/`
+
+### Inputs
+
+1. **Reviewed test cases** — files under `testcase/md/` (approved by `review-backend-cases-pi`).
+2. **Target project conventions** — read `conftest.py`, `pytest.ini` / `pyproject.toml` to understand conventions, but do NOT modify them.
+
+Do NOT re-read source documents. Use the reviewed cases only.
+
+### Conversion Rules
+
+#### File Naming
+
+- Every test file must start with `test_` prefix (e.g. `test_order.py`, `test_user_api.py`)
+- pytest collects tests from files matching `test_*.py` or `*_test.py` — use `test_` prefix exclusively
+- Never create test files without the `test_` prefix
+
+#### Write Boundary
+
+- Only **create new** files under writeSet:
+  - `testcase/**/test_*.py`
+  - `testcase/**/helpers/**` (optional pure helpers)
+  - `testcase/**/factories/**` (optional test data factories)
+- Do NOT modify existing files: `conftest.py`, `pytest.ini`, `pyproject.toml`, `setup.cfg`, `__init__.py`, or any other framework/config file
+- Reuse existing fixtures; if required helpers are missing, create NEW helper/factory modules under the writeSet paths above — never edit root conftest
+- Read existing framework files to understand conventions, but treat them as immutable
+- Do NOT write production code, `.env`, secrets, or credential files
+
+#### Naming Conflict Resolution
+
+- If a file with the target name already exists under `testcase/`, add a numeric suffix: `test_order.py` → `test_order_01.py` → `test_order_02.py`
+- Never overwrite or append to existing files — each test script must be a standalone file
+- Check for existing files before writing; if `test_<module>.py` exists, use `test_<module>_01.py`
+
+#### 1:1 Traceability
+
+Every functional test case ID (`BE-<MODULE>-<NNN>`) must map to exactly one pytest function:
+
+```python
+# testcase/md/BE-ORDER-001 → testcase/test_order.py
+def test_BE_ORDER_001_create_order_with_valid_data():
+    """BE-ORDER-001: Create order with valid request body."""
+    ...
+```
+
+- Function name: `test_<CASE_ID_with_underscores>` (e.g. `test_BE_ORDER_001_...`)
+- Docstring first line: `<CASE_ID>: <Case Title>`
+
+#### File Organization
+
+- All test files go under `testcase/` directory in the host project root
+- Group test files by MODULE segment: `BE-ORDER-*` → `testcase/test_order.py`, `BE-USER-*` → `testcase/test_user.py`
+- Follow existing project conventions for import style, fixture scope
+
+#### Fixture Strategy
+
+- Reuse existing project fixtures from `conftest.py` when available (read-only)
+- Do not create or modify root fixture/configuration files (`conftest.py`, pytest.ini, …)
+- Optional NEW helpers/factories may live under `testcase/**/helpers/**` or `testcase/**/factories/**` only
+- Prefer `@pytest.fixture(scope="function")` for test isolation
+- Use `@pytest.mark.parametrize` for boundary condition cases with multiple inputs
+
+#### Test Integrity
+
+- Tests verify implementation correctness — if a test fails, the implementation likely has a bug, not the test
+- Do NOT weaken assertions, remove test cases, or modify test logic to make tests pass
+- Do NOT add workarounds, skips, or try/except blocks to hide failures without explicit justification
+- Report all failures honestly in the output; the downstream `execute-backend-pytest-shell` node captures exit codes and stdout/stderr as-is
+
+#### Test Data Preparation Rules (MUST follow)
+
+**When Setup is Needed**
+
+Setup phase is REQUIRED only when test cases need pre-existing data:
+- Query/Read APIs: need data to exist before querying
+- Update/Delete APIs: need data to exist before modifying
+- State transition tests: need data in specific state
+
+Setup phase is NOT needed for:
+- Create APIs: testing the creation itself
+- Validation tests: testing input validation with invalid data
+
+**Data Setup Strategy**
+
+When setup is needed:
+1. Use `@pytest.fixture(scope='module')` or `@pytest.fixture(scope='session')` to prepare shared test data
+2. All test cases in the file share the same pre-constructed data
+
+**Data Construction Priority**
+
+1. **API-first**: Use documented APIs from `analyze-inputs-pi` / reviewed cases
+2. **Reuse existing conftest fixtures** (read-only)
+3. **Direct DB writes are last resort** and only via safe test-DB fixtures with rollback/isolation
+4. If neither API nor safe DB fixture exists, **skip with an explicit gap note** — do not invent credentials or touch live data
+
+**API Data Construction**
+
+- Prefer the `analyze-inputs-pi` API Endpoints section and reviewed cases for method/path/fields
+- Chain API calls only when cases document multi-step preconditions
+- Store created resource IDs in fixtures for reuse
+- Do **not** broadly search host route/controller trees for secrets, `.env`, private keys, or production configs
+- Read host API definitions only when needed to resolve a field name already referenced by reviewed cases
+
+**Database Data Construction (restricted)**
+
+- Allowed only via existing `conftest.py` test-DB fixtures with transaction rollback or equivalent isolation
+- Never hardcode connection strings, passwords, tokens, or cloud credentials
+- Never target production/shared non-test databases
+- If isolation is unclear, report the gap instead of writing DB rows
+
+#### Assertion Rules (MUST follow)
+
+**Positive Path (成功场景)**
+
+MUST assert ALL of the following:
+1. HTTP status code: as defined in API spec (e.g. 200, 201)
+2. Response structure: key fields exist in response body
+3. Specific values: each field equals expected value from test case
+4. Data type: each field is correct type
+
+**Negative Path (异常场景)**
+
+MUST assert ALL of the following:
+1. HTTP status code: as defined in API spec (e.g. 400, 404, 500)
+2. Error code field: field name from API spec (e.g. code, error_code, errcode, ret)
+3. Error message field: field name from API spec (e.g. message, msg, errmsg, error)
+
+**Field Name Resolution**
+
+Field names MUST come from the upstream `analyze-inputs-pi` output (API Endpoints section), NOT hardcoded. For example:
+- If API spec defines `{"ret": 0, "msg": "success"}`, assert `response.json()["ret"]` and `response.json()["msg"]`
+- If API spec defines `{"code": 4001, "message": "error"}`, assert `response.json()["code"]` and `response.json()["message"]`
+
+
+#### Conditional Test Implementation (include ONLY if test cases exist)
+
+- **Authentication tests**: implement ONLY if `testcase/md/` contains auth-related cases
+  - Use `@pytest.mark.auth` marker
+  - Test no token, expired token, invalid token, insufficient permissions, cross-user access
+- **Timeout tests**: implement ONLY if `testcase/md/` contains timeout-related cases
+  - Use `@pytest.mark.timeout` marker
+  - Use `unittest.mock.patch` or `pytest-mock` to simulate slow responses
+- If no such cases exist in the reviewed test cases, do NOT add these tests
+
+#### Markers
+
+- `@pytest.mark.positive` — happy path cases
+- `@pytest.mark.negative` — error/exception cases
+- `@pytest.mark.boundary` — edge cases
+- `@pytest.mark.<MODULE>` — module-specific marker (e.g. `@pytest.mark.order`)
+
+#### Skip Policy
+
+If a test case cannot be automated (requires external service not mockable, requires manual verification), add it with `@pytest.mark.skip(reason="...")` and document the reason. Do not omit the function — traceability requires it exists.
+
+### Output Shape (after summary line)
+
+After the mandatory summary line, provide:
+
+1. **Generated Files** — list of files written under `tests/backend/`.
+2. **Function Mapping Table** — `| Test Case ID | Pytest Function | File | Marker |`.
+3. **Skipped Cases** — if any, list with reason.
+4. **Conventions Observed** — note project fixtures/config discovered and followed.
+5. **Residual Risks** — cases that may need manual verification or environment setup.
+
+Do not include chain-of-thought. Do not write root `artifacts/**`.