tuner-testkit 4.0.2__tar.gz → 4.2.0__tar.gz

tuner_testkit-4.2.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: tuner-testkit
+Version: 4.2.0
+Summary: Shared test runtime, recorders, and DNA overlay for SUT test repos
+Author: tuner-testkit contributors
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Provides-Extra: db
+Requires-Dist: pymysql>=1.2.0; extra == "db"
+Requires-Dist: pymssql>=2.3.0; extra == "db"
+Requires-Dist: psycopg[binary]>=3.2; extra == "db"
+Requires-Dist: sqlalchemy>=2.0; extra == "db"
+Provides-Extra: api
+Requires-Dist: requests>=2.33.1; extra == "api"
+Provides-Extra: web-ui
+Requires-Dist: playwright>=1.54.0; extra == "web-ui"
+Provides-Extra: phone-ui
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1.0; extra == "excel"
+Provides-Extra: fake
+Requires-Dist: faker>=37.0.0; extra == "fake"
+Provides-Extra: mock
+Requires-Dist: fastapi>=0.115.0; extra == "mock"
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == "mock"
+Requires-Dist: httpx>=0.28.0; extra == "mock"
+Provides-Extra: recorder
+Requires-Dist: playwright>=1.54.0; extra == "recorder"
+Requires-Dist: mitmproxy>=11.1.3; extra == "recorder"
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.3; extra == "test"
+Requires-Dist: openpyxl>=3.1.0; extra == "test"
+Requires-Dist: httpx>=0.28.0; extra == "test"
+Provides-Extra: bdd
+Requires-Dist: behave>=1.2.6; extra == "bdd"
+Requires-Dist: playwright>=1.54.0; extra == "bdd"
+Requires-Dist: behave-html-pretty-formatter>=1.16.1; extra == "bdd"
+Provides-Extra: all
+Requires-Dist: tuner-testkit[api,bdd,db,excel,fake,mock,phone-ui,recorder,test,web-ui]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: tuner-testkit[all]; extra == "dev"
+Dynamic: license-file
+
+# tuner-testkit
+
+发行名 **`tuner-testkit`**，导入名 **`tuner_testkit`**。给被测系统（SUT）测试仓提供公共运行库与 CLI（db / API / Web UI / 录制 / mock），以及 Cursor/git **DNA**（rules、skills、hooks）。
+
+业务资产（page/api objects、action words、features）留在**各项目仓**的 `packages/` 与 `tests/`，不进本包。平台发新版本后，下游用 `uv` 按需升级，不必再整树拷贝运行库。
+
+---
+
+## 标准作业流程
+
+### 1. 工具域：只装核心 kit（能 `tuner-init` 即可）
+
+`uv tool install` 和业务仓 `.venv` 是两套环境。下游在 **tool 域只装默认 wheel**，用来拿 `tuner-init` / `tuner-dna`；**不要**在 tool 域打开 `[db]` / `[api]` 等 extra。
+
+```bash
+uv tool install tuner-testkit
+```
+
+入口命令是 `tuner-init`、`tuner-dna` 等（`tuner-*`），**没有** `tuner-testkit` 这个 script。`tuner-dump-ddl`、`tuner-recorder` 等依赖 extra 的 CLI，请在业务仓用 `uv run …` 跑，走该仓 `.venv`。
+
+### 2. 初始化测试仓
+
+```bash
+tuner-init scaffold ../my-sut-tests
+cd ../my-sut-tests
+uv sync
+```
+
+`scaffold` 会铺六层目录、写入依赖 `tuner-testkit[db,api]` 的 `pyproject.toml`，并执行一次 `tuner-dna sync`（把 `.cursor/`、`docs/spec/`、`tools/git-hooks/` 放进**项目树**）。可在任意目录运行，不必先有测试仓。不要用 `tuner-testkit init repo`。
+
+`uv sync` 把 **db / api 装进业务仓 `.venv`**，不是 tool 域。已有项目仓则在该仓根目录：
+
+```bash
+uv add "tuner-testkit[db,api]>=4.0.0"
+uv sync
+```
+
+Web UI / 合录等按需再加 extra：
+
+```bash
+uv add "tuner-testkit[web-ui]"
+uv add "tuner-testkit[recorder]"
+```
+
+测 kit 全能力（平台狗食仓等）一次打开全部能力 extra：
+
+```bash
+uv add "tuner-testkit[all]"
+uv sync
+```
+
+### 3. 开始写业务
+
+在**项目仓**里写，不要改 site-packages 里的 kit：
+
+| 你写什么 | 放哪里 |
+| --- | --- |
+| 页面 / 接口资产 | `packages/page_objects/`、`packages/api_objects/` |
+| 业务动作 | `packages/action_words/` |
+| BDD / pytest | `tests/features/`、`tests/pytest/` |
+| 知识（DDL、用例） | `assets/` |
+| 本仓私有工具 | `apps/`（`python -m apps.<name>`） |
+
+代码里 `from tuner_testkit.db import …` / `from tuner_testkit.page_test import …`。密钥只放本机 `config/env_local.py` 或环境变量（`TUNER_ENV`、`TUNER_DB_<ALIAS>_*`），**不要提交**。
+
+录制产物同样写到项目仓 `packages/`，不会写进 venv。
+
+### 4. 获取 PyPI 上的更新
+
+平台发新版本后，下游从 [PyPI：tuner-testkit](https://pypi.org/project/tuner-testkit/) 取 wheel，**不要**再拷本仓源码。tool 域和业务仓 `.venv` 是两份安装，**两边都要升**，再铺 DNA。
+
+**先看当前装的是哪一版、PyPI 最新是哪一版：**
+
+```bash
+uv tool list                          # tool 域里的 tuner-testkit
+cd ../my-sut-tests
+uv pip show tuner-testkit             # 业务仓 .venv
+```
+
+发行说明见 [`docs/changelog/FRAMEWORK.md`](docs/changelog/FRAMEWORK.md) 与该版本的 `docs/changelog/TEMPLATE-*.md`。
+
+**① tool 域（只升核心 CLI）**
+
+```bash
+uv tool upgrade tuner-testkit
+```
+
+升的是 `tuner-init` / `tuner-dna` 所在环境。这里仍然**不要**加 `[db]` / `[api]`。尚未 `uv tool install` 过则先执行第 1 节。
+
+**② 业务仓 `.venv`（升运行库 + extras）**
+
+在**项目仓根目录**改依赖并同步 lock。保留你原来打开的 extra（普通仓 `[db,api]`，狗食/全能力仓 `[all]`）：
+
+```bash
+# 钉到某一发行版（推荐，和团队 lock 一致）
+uv add "tuner-testkit[db,api]==4.2.0"
+
+# 或只抬下限，让解析器选允许范围内的最新
+# uv add "tuner-testkit[db,api]>=4.2.0"
+
+uv sync
+```
+
+已经写过 `>=4.0.0`、只想把 lock 里的 kit 升到 PyPI 最新：
+
+```bash
+uv lock --upgrade-package tuner-testkit
+uv sync
+```
+
+只改 `pyproject.toml` 里的版本再 `uv lock` / `uv sync` 也可以。一个 wheel 不能「只升 web-ui、钉死旧 db」。
+
+**③ 同步 DNA 并提交**
+
+`uv add` / `uv sync` 只更新 site-packages 里的运行库。Cursor 读的是项目树里的 `.cursor/`、`docs/spec/`、`tools/git-hooks/`，必须再铺一层：
+
+```bash
+tuner-dna sync
+tuner-dna check
+git add -A && git commit
+```
+
+`tuner-dna check` 核对项目树 DNA 是否与**当前 PATH 上那份** kit 一致。建议先 `uv tool upgrade`，再 `sync`，避免 CLI 还是旧包、`.venv` 已是新包。
+
+新仓第一次仍用第 2 节的 `tuner-init scaffold`（会写依赖并做一次 `tuner-dna sync`），不是每次发版都重新 scaffold。
+
+`[phone-ui]` 为预留空 extra，4.0 未实现。
+
+---
+
+## extras
+
+| extra | 内容 |
+| --- | --- |
+| （默认 wheel） | `config` / `logging`、`tuner-init`、`tuner-dna`（tool 域只装这个） |
+| `[db]` | MySQL / SQL Server / PostgreSQL（装在业务仓 `.venv`） |
+| `[api]` | `api_test`（HTTP 客户端） |
+| `[web-ui]` | `page_test` + Playwright |
+| `[phone-ui]` | 预留，无实现 |
+| `[recorder]` | 合录 / 仅 UI / mitmproxy 代理 |
+| `[mock]` | 按冻结的 api_objects 回放 |
+| `[excel]` / `[fake]` | 表格 / 假数据 |
+| `[bdd]` / `[test]` | behave / pytest |
+| `[all]` | 元 extra：上述能力 extra 的并集（不含 `[dev]`） |
+| `[dev]` | `tuner-testkit[all]`，给本仓 editable 开发 |
+
+CLI 与 `python -m tuner_testkit.…` 等价，例如 `tuner-recorder`、`tuner-page-recorder`、`tuner-api-recorder`、`tuner-mock-server`。依赖 extra 的命令在业务仓用 `uv run tuner-dump-ddl` / `uv run tuner-recorder`。
+
+---
+
+## 安全
+
+不得把 token、cookie、Authorization、密码、session 写入仓库（含 capture 与 api_objects）。凭证只允许运行时注入。
+
+---
+
+## 本仓库（平台源码）
+
+克隆后在仓库根目录开发 kit 本身：
+
+```powershell
+uv venv
+uv sync --extra all
+```
+
+`uv sync --extra dev` 与 `--extra all` 等价（`dev` 只是引用 `[all]`）。
+
+4.2.0 发行说明见 [`docs/changelog/TEMPLATE-4.2.0.md`](docs/changelog/TEMPLATE-4.2.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。

tuner_testkit-4.2.0/README.md

@@ -0,0 +1,168 @@
+# tuner-testkit
+
+发行名 **`tuner-testkit`**，导入名 **`tuner_testkit`**。给被测系统（SUT）测试仓提供公共运行库与 CLI（db / API / Web UI / 录制 / mock），以及 Cursor/git **DNA**（rules、skills、hooks）。
+
+业务资产（page/api objects、action words、features）留在**各项目仓**的 `packages/` 与 `tests/`，不进本包。平台发新版本后，下游用 `uv` 按需升级，不必再整树拷贝运行库。
+
+---
+
+## 标准作业流程
+
+### 1. 工具域：只装核心 kit（能 `tuner-init` 即可）
+
+`uv tool install` 和业务仓 `.venv` 是两套环境。下游在 **tool 域只装默认 wheel**，用来拿 `tuner-init` / `tuner-dna`；**不要**在 tool 域打开 `[db]` / `[api]` 等 extra。
+
+```bash
+uv tool install tuner-testkit
+```
+
+入口命令是 `tuner-init`、`tuner-dna` 等（`tuner-*`），**没有** `tuner-testkit` 这个 script。`tuner-dump-ddl`、`tuner-recorder` 等依赖 extra 的 CLI，请在业务仓用 `uv run …` 跑，走该仓 `.venv`。
+
+### 2. 初始化测试仓
+
+```bash
+tuner-init scaffold ../my-sut-tests
+cd ../my-sut-tests
+uv sync
+```
+
+`scaffold` 会铺六层目录、写入依赖 `tuner-testkit[db,api]` 的 `pyproject.toml`，并执行一次 `tuner-dna sync`（把 `.cursor/`、`docs/spec/`、`tools/git-hooks/` 放进**项目树**）。可在任意目录运行，不必先有测试仓。不要用 `tuner-testkit init repo`。
+
+`uv sync` 把 **db / api 装进业务仓 `.venv`**，不是 tool 域。已有项目仓则在该仓根目录：
+
+```bash
+uv add "tuner-testkit[db,api]>=4.0.0"
+uv sync
+```
+
+Web UI / 合录等按需再加 extra：
+
+```bash
+uv add "tuner-testkit[web-ui]"
+uv add "tuner-testkit[recorder]"
+```
+
+测 kit 全能力（平台狗食仓等）一次打开全部能力 extra：
+
+```bash
+uv add "tuner-testkit[all]"
+uv sync
+```
+
+### 3. 开始写业务
+
+在**项目仓**里写，不要改 site-packages 里的 kit：
+
+| 你写什么 | 放哪里 |
+| --- | --- |
+| 页面 / 接口资产 | `packages/page_objects/`、`packages/api_objects/` |
+| 业务动作 | `packages/action_words/` |
+| BDD / pytest | `tests/features/`、`tests/pytest/` |
+| 知识（DDL、用例） | `assets/` |
+| 本仓私有工具 | `apps/`（`python -m apps.<name>`） |
+
+代码里 `from tuner_testkit.db import …` / `from tuner_testkit.page_test import …`。密钥只放本机 `config/env_local.py` 或环境变量（`TUNER_ENV`、`TUNER_DB_<ALIAS>_*`），**不要提交**。
+
+录制产物同样写到项目仓 `packages/`，不会写进 venv。
+
+### 4. 获取 PyPI 上的更新
+
+平台发新版本后，下游从 [PyPI：tuner-testkit](https://pypi.org/project/tuner-testkit/) 取 wheel，**不要**再拷本仓源码。tool 域和业务仓 `.venv` 是两份安装，**两边都要升**，再铺 DNA。
+
+**先看当前装的是哪一版、PyPI 最新是哪一版：**
+
+```bash
+uv tool list                          # tool 域里的 tuner-testkit
+cd ../my-sut-tests
+uv pip show tuner-testkit             # 业务仓 .venv
+```
+
+发行说明见 [`docs/changelog/FRAMEWORK.md`](docs/changelog/FRAMEWORK.md) 与该版本的 `docs/changelog/TEMPLATE-*.md`。
+
+**① tool 域（只升核心 CLI）**
+
+```bash
+uv tool upgrade tuner-testkit
+```
+
+升的是 `tuner-init` / `tuner-dna` 所在环境。这里仍然**不要**加 `[db]` / `[api]`。尚未 `uv tool install` 过则先执行第 1 节。
+
+**② 业务仓 `.venv`（升运行库 + extras）**
+
+在**项目仓根目录**改依赖并同步 lock。保留你原来打开的 extra（普通仓 `[db,api]`，狗食/全能力仓 `[all]`）：
+
+```bash
+# 钉到某一发行版（推荐，和团队 lock 一致）
+uv add "tuner-testkit[db,api]==4.2.0"
+
+# 或只抬下限，让解析器选允许范围内的最新
+# uv add "tuner-testkit[db,api]>=4.2.0"
+
+uv sync
+```
+
+已经写过 `>=4.0.0`、只想把 lock 里的 kit 升到 PyPI 最新：
+
+```bash
+uv lock --upgrade-package tuner-testkit
+uv sync
+```
+
+只改 `pyproject.toml` 里的版本再 `uv lock` / `uv sync` 也可以。一个 wheel 不能「只升 web-ui、钉死旧 db」。
+
+**③ 同步 DNA 并提交**
+
+`uv add` / `uv sync` 只更新 site-packages 里的运行库。Cursor 读的是项目树里的 `.cursor/`、`docs/spec/`、`tools/git-hooks/`，必须再铺一层：
+
+```bash
+tuner-dna sync
+tuner-dna check
+git add -A && git commit
+```
+
+`tuner-dna check` 核对项目树 DNA 是否与**当前 PATH 上那份** kit 一致。建议先 `uv tool upgrade`，再 `sync`，避免 CLI 还是旧包、`.venv` 已是新包。
+
+新仓第一次仍用第 2 节的 `tuner-init scaffold`（会写依赖并做一次 `tuner-dna sync`），不是每次发版都重新 scaffold。
+
+`[phone-ui]` 为预留空 extra，4.0 未实现。
+
+---
+
+## extras
+
+| extra | 内容 |
+| --- | --- |
+| （默认 wheel） | `config` / `logging`、`tuner-init`、`tuner-dna`（tool 域只装这个） |
+| `[db]` | MySQL / SQL Server / PostgreSQL（装在业务仓 `.venv`） |
+| `[api]` | `api_test`（HTTP 客户端） |
+| `[web-ui]` | `page_test` + Playwright |
+| `[phone-ui]` | 预留，无实现 |
+| `[recorder]` | 合录 / 仅 UI / mitmproxy 代理 |
+| `[mock]` | 按冻结的 api_objects 回放 |
+| `[excel]` / `[fake]` | 表格 / 假数据 |
+| `[bdd]` / `[test]` | behave / pytest |
+| `[all]` | 元 extra：上述能力 extra 的并集（不含 `[dev]`） |
+| `[dev]` | `tuner-testkit[all]`，给本仓 editable 开发 |
+
+CLI 与 `python -m tuner_testkit.…` 等价，例如 `tuner-recorder`、`tuner-page-recorder`、`tuner-api-recorder`、`tuner-mock-server`。依赖 extra 的命令在业务仓用 `uv run tuner-dump-ddl` / `uv run tuner-recorder`。
+
+---
+
+## 安全
+
+不得把 token、cookie、Authorization、密码、session 写入仓库（含 capture 与 api_objects）。凭证只允许运行时注入。
+
+---
+
+## 本仓库（平台源码）
+
+克隆后在仓库根目录开发 kit 本身：
+
+```powershell
+uv venv
+uv sync --extra all
+```
+
+`uv sync --extra dev` 与 `--extra all` 等价（`dev` 只是引用 `[all]`）。
+
+4.2.0 发行说明见 [`docs/changelog/TEMPLATE-4.2.0.md`](docs/changelog/TEMPLATE-4.2.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。

{tuner_testkit-4.0.2 → tuner_testkit-4.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tuner-testkit"
-version = "4.0.2"
+version = "4.2.0"
 description = "Shared test runtime, recorders, and DNA overlay for SUT test repos"
 readme = "README.md"
 license = "MIT"
@@ -51,23 +51,12 @@ bdd = [
     "playwright>=1.54.0",
     "behave-html-pretty-formatter>=1.16.1",
 ]
+# Union of capability extras (excludes `dev` to avoid a cycle).
+all = [
+    "tuner-testkit[db,api,web-ui,phone-ui,excel,fake,mock,recorder,test,bdd]",
+]
 dev = [
-    "pymysql>=1.2.0",
-    "pymssql>=2.3.0",
-    "psycopg[binary]>=3.2",
-    "sqlalchemy>=2.0",
-    "requests>=2.33.1",
-    "pydantic>=2",
-    "faker>=37.0.0",
-    "openpyxl>=3.1.0",
-    "fastapi>=0.115.0",
-    "uvicorn[standard]>=0.32.0",
-    "httpx>=0.28.0",
-    "pytest>=9.0.3",
-    "behave>=1.2.6",
-    "playwright>=1.54.0",
-    "behave-html-pretty-formatter>=1.16.1",
-    "mitmproxy>=11.1.3",
+    "tuner-testkit[all]",
 ]
 
 [project.scripts]

{tuner_testkit-4.0.2 → tuner_testkit-4.2.0}/tuner_testkit/__init__.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "4.0.2"
+__version__ = "4.2.0"

{tuner_testkit-4.0.2 → tuner_testkit-4.2.0}/tuner_testkit/action_words/__init__.py

@@ -15,7 +15,7 @@ CLI::
     uv run python -m tuner_testkit.action_words list
     uv run python -m tuner_testkit.action_words describe <word_id>
     uv run python -m tuner_testkit.action_words run <word_id> --params '{...}'
-    uv run python -m tuner_testkit.action_words catalog --out report/action_words_catalog.json
+    uv run python -m tuner_testkit.action_words catalog --out artifacts/catalogs/action_words_catalog.json
 """
 from __future__ import annotations
 

{tuner_testkit-4.0.2 → tuner_testkit-4.2.0}/tuner_testkit/action_words/__main__.py

@@ -7,7 +7,7 @@
     uv run python -m tuner_testkit.action_words run db_seed.create_example --params "{...}"
     uv run python -m tuner_testkit.action_words run db_seed.create_example --params-file p.json
     uv run python -m tuner_testkit.action_words run db_seed.create_example --example
-    uv run python -m tuner_testkit.action_words catalog --out report/action_words_catalog.json
+    uv run python -m tuner_testkit.action_words catalog --out artifacts/catalogs/action_words_catalog.json
 
 ``run`` 未提供 ``--params`` 时使用 ``{}``（即全部默认值）；``--example``
 使用 word 自带的 ``example_params`` 样例运行。

tuner_testkit-4.2.0/tuner_testkit/apps/dna/dna_payload/.cursor/agents/bdd-asset-pipeline.md

@@ -0,0 +1,106 @@
+---
+name: bdd-asset-pipeline
+version: 2.0.0
+description: Lower-half of SUT self-learning — Feature Sets + design knowledge → Reuse Analysis → Freeze API Objects → Maintain Page Objects → Maintain Steps → behave regression. Use only for behave/BDD automation assets. Do NOT use when the user explicitly requests pytest. Do NOT use this agent as the explore-first entry; start from docs/spec/sut-self-learning.md instead.
+---
+
+# BDD Asset Pipeline Agent (lower half)
+
+## Purpose
+
+Coordinate the **lower half** of SUT self-learning once a feature-set entry
+and (when available) design knowledge exist:
+
+Feature Set item + `assets/design/**` → (optional MCP re-run) → Reuse vs
+Create → Freeze API Objects → Update Page Objects → Implement Steps →
+Regression run → Report.
+
+The **upper half** (explore SUT → capability map + design knowledge) is
+specified in `docs/spec/sut-self-learning.md`. Do not start this agent
+when the task is still "learn the SUT / explore pages" with no feature
+intent yet.
+
+## Applicability
+
+- **Use this agent** when generating or maintaining `.feature` / behave
+  steps / BDD UI·API assets **from** a feature-set entry (and design notes).
+- **Do not use this agent** when the user **explicitly** asks for **pytest**.
+- **Do not use this agent** as the first step of explore-first learning.
+
+## Inputs (required)
+
+- At least one feature-set entry (a `.feature` to write/update, or a
+  scenario intent grounded in `assets/explore/**` / `assets/usecases/**`).
+- Prefer also: matching `assets/design/<app>/<route-slug>.md` so assertions
+  know which tables to check and which to skip as `noise`.
+
+## Non-negotiable workflow contract (hard gates)
+
+Same three gates as `.cursor/rules/bdd-pipeline-gates.mdc` v3:
+
+- **Gate 1: Evidence is mandatory** (explore session OR feature run). Cite
+  `artifacts/evidence/<run_id>/`. Do not skip MCP just because local
+  `sync_playwright` UI steps pass. If MCP is blocked, stop and report.
+- **Gate 2: Freeze is mandatory when capture has eligible routes**.
+- **Gate 3: Run the stages that actually exist** — do not fail a missing
+  API/UI stage that was never authored.
+
+## Skills to use (in order)
+
+1. **Feature authoring / rewrite** — `feature-authoring` → `tests/features/**/*.feature`
+2. **Feature review / lint** — `feature-review-lint`
+3. **Execute scenario & capture evidence** (if no reusable evidence) —
+   `run-feature-playwright-mcp` → sanitized `artifacts/evidence/<run_id>/`
+4. **Reuse analysis** — `reuse-analysis`
+5. **Freeze captures into API assets** — `freeze-api-objects`
+6. **Maintain UI assets** — `maintain-page-objects`
+7. **Implement/repair behave steps** — `maintain-behave-steps`
+
+Before writing Then-assertions, **read `assets/design/**`**:
+
+- Assert `writes` (business tables) via `db_assert` / API extracts.
+- Never assert `noise` tables (audit / operation_log) as business outcomes.
+- Use `correlate` / `identity` to locate rows; do not hardcode scenario ids
+  into APIModel asserts.
+
+## Cross-cutting constraints (must always hold)
+
+- No secrets in repo: tokens/cookies/authorization/session secrets must never be written.
+- Steps do not contain selectors or handcrafted requests.
+- Assertions are stable and observable; no scenario constants inside API Object asserts.
+- API execution is triggered via `APIModel.execute()` after `set_*` / `override_*`.
+- **Binary / form APIs**: `tuner_testkit.api_test` always returns
+  `ApiResponse.content` (raw bytes). Use `APIModel.body_format="form"` when
+  capture shows `application/x-www-form-urlencoded`. For xlsx/CSV exports,
+  freeze a route-aligned asset that asserts HTTP 200 only; parse bodies with
+  `tuner_testkit.excel` in steps or `packages/<domain>` — not in
+  `packages/api_objects/`.
+
+## Repo conventions this agent must enforce
+
+### Stage mode (`behave --stage`)
+
+- `behave --stage <name>` changes discovery:
+  - steps dir becomes `tests/features/<name>_steps/` (top-level `*.py` only)
+  - environment file becomes `tests/features/<name>_environment.py` (if present)
+- Therefore `tests/features/ui_steps/` and `tests/features/api_steps/` **must**
+  have a top-level loader that imports the actual step modules.
+
+### Step file granularity (required)
+
+- UI: `tests/features/ui_steps/given.py`, `when.py`, `then.py`
+- API: `tests/features/api_steps/given.py`, `when.py`, `then.py`
+- **Do not** create domain-split step files like `auth_api_then.py`.
+  Reuse is achieved by **phrases and functions**, not by multiplying files.
+
+## Done criteria
+
+- Feature scenarios read well and pass lint rules.
+- Steps are thin and reusable.
+- `packages/api_objects/` and `packages/page_objects/` are the only place
+  with implementation details (per layer).
+- Assertions consult design knowledge when it exists.
+- Evidence is on disk under `artifacts/evidence/<run_id>/` (sanitized).
+- `behave --stage ui` succeeds for UI features that exist.
+- `behave --stage api` succeeds for API features that exist (or `--dry-run`
+  with documented TODO).

{tuner_testkit-4.0.2 → tuner_testkit-4.2.0}/tuner_testkit/apps/dna/dna_payload/.cursor/rules/assets-knowledge.mdc

@@ -2,28 +2,34 @@
 description: assets/ is the knowledge base for humans and the LLM; enforce provenance metadata, raw-vs-curated boundaries, and grounding (consult INDEX before generating)
 globs: assets/**
 alwaysApply: false
-version: 1.0.0
+version: 1.1.0
 ---
 
 # assets — 知识层硬约束
 
 `assets/` 存放给人和 LLM 阅读、作为生成测试代码/工具依据的知识。完整规范见
 `docs/spec/assets-knowledge-syntax.md`；全局发现入口见根 `INDEX.md`。
+SUT 自学习见 `docs/spec/sut-self-learning.md`；design schema 见
+`docs/spec/design-knowledge-syntax.md`。
 
 ## Grounding（生成前必读）
 
 - **生成任何测试 / action word / api·page object / 工具之前**，先查根 `INDEX.md`
-  检索相关 domain 的知识（真实 DDL 列名、`assets/sql` 真实业务 SQL、`usecases` /
-  `domain-notes`），以此为依据，**不要凭空臆造**列名、接口字段、业务规则。
-- 缺知识时先回填：`/dump-ddl` 或 `python -m tuner_testkit.apps.dump_ddl --all --datasource <alias>`（DDL）、
-  `python -m tuner_testkit.apps.recorder`（合录）或 `python -m tuner_testkit.apps.api_recorder`（代理抓包），再进入生成。
+  （及存在时的 `INDEX.project.md`）检索相关 domain 的知识（真实 DDL 列名、
+  `assets/sql`、`usecases` / `domain-notes` / `explore` / `design`），
+  **不要凭空臆造**列名、接口字段、业务规则。
+- 缺知识时先回填：`/dump-ddl` 或 `python -m tuner_testkit.apps.dump_ddl`、
+  Playwright MCP 探索（落盘 `artifacts/evidence/<run_id>/`）、
+  `python -m tuner_testkit.apps.recorder` / `api_recorder`，再进入生成。
 
 ## 目录与元数据
 
 - 目录分类固定：`ddl/<datasource>/`、`sql/`、`usecases/<domain>/`、
-  `domain-notes/<domain>/`、`testreport/`（新增类别前先看 spec）。
+  `domain-notes/<domain>/`、`explore/<app>/`、`design/<app>/`、`testreport/`
+  （新增类别前先改 spec，再改本 rule）。
 - 人工/半自动区文件头必须带元数据：`domain / source / date / version / confidence`
   （Markdown 用 YAML front-matter，SQL 用顶部 `--` 注释）。
+- `explore/` 与 `design/` 还应填 `evidence`（run_id 列表）。
 - `confidence: high` 表示人工核实过——LLM 应优先采信。
 
 ## raw vs curated
@@ -33,10 +39,9 @@ version: 1.0.0
 
 ## 变更留痕
 
-- 自动区（`ddl/`）更新由工具写 `assets/CHANGELOG.md`（见 `apps-authoring-syntax.md`）；
-  人不手改自动区语义，要更新就重跑工具。
-- curated 更新 → bump `version` + 正文追加变更说明；随后由 `maintain-index` skill
-  增量更新根 `INDEX.md`。
+- 自动区（`ddl/`）更新由工具写 `assets/CHANGELOG.md`；人不手改自动区语义。
+- curated 更新 → bump `version` + 正文追加变更说明；随后由 `maintain-index`
+  增量更新 `INDEX.md` / `INDEX.project.md`。
 
 ## 禁止
 

{tuner_testkit-4.0.2 → tuner_testkit-4.2.0}/tuner_testkit/apps/dna/dna_payload/.cursor/rules/bdd-asset-layering.mdc

@@ -2,7 +2,7 @@
 description: Enforce layered boundaries between feature/steps/action_words/page_objects/api_objects and tuner_testkit runtime; no selector or request leakage across layers
 globs: **/*.py
 alwaysApply: false
-version: 1.3.0
+version: 1.3.1
 ---
 
 # Asset Layering — boundary rules per layer
@@ -40,7 +40,7 @@ Each layer owns one responsibility. Leakage across layers (e.g. selectors in ste
 
 ## Cross-cutting
 
-- **No secrets in repo**, ever: `Authorization`, `Cookie`, `Set-Cookie`, `*token*`, `*secret*`, `*password*`, `*session*`. Also applies to captures under `report/` / `testcase/`.
+- **No secrets in repo**, ever: `Authorization`, `Cookie`, `Set-Cookie`, `*token*`, `*secret*`, `*password*`, `*session*`. Also applies to captures under `artifacts/evidence/`.
 - **Evidence-driven edits**: Page/API object changes must be backed by Playwright MCP snapshots, `tuner-recorder` / `tuner-api-recorder` captures (`python -m tuner_testkit.apps.recorder` / `api_recorder`), or run_summary findings; avoid locator/path guesses.
 - **`tests/**` must not import `apps.*`**. Action words for BDD/pytest stay in
   `tuner_testkit.action_words`. Opt into Plane with `@plane_db_seed` (etc.) from