# Supplemental review rules These rules supplement, rather than replace, `README.md` and the canonical workspace review rules. ## Runner-derived rules - **R1 — Embedded JSON and request type (P1):** Require non-empty JSON objects for `request` and `expect`, and a JSON object for non-null `save`. Accept only `http`, `cmd_aws`, `cmd_gcp`, `cmd_azure`, `cmd_mysqlsh`, and `cmd_aliyun`, and match command names to the request type. The deterministic checker exits nonzero when it reports findings. Reference: `/functional-test/cases/openapidedicated/autogencase/model/generationsteps.go` (`ParseHTTPRequestSpec`, `ParseCommandSpec`) and `Scenario_suite_test.go` (`SetupSuite`). - **R2 — File order is execution order (P1):** For filesystem YAML, the suite appends and executes steps in YAML sequence; it does not sort them by `order`. Require strictly increasing, unique order values unless evidence proves an exception. Reference: `Scenario_suite_test.go` (`SetupSuite`, `Test_001_ExecuteActions`) and [PR #114 duplicate-order review](https://github.com/tidbcloud/APITestGen/pull/114#discussion_r2533022128). - **R3 — Placeholder binding (P1):** Bind path, body, and command placeholders through `path_params`, `body_params`, and `args_params`. A command argument starting with `--` is never placeholder-expanded, so use separate flag and value arguments. Typed body placeholders (`integer`, `number`) work only when the full string is one placeholder. Reference: `actionbuilder.go` (`buildPathParams`, `resolveTypedBodyPlaceholder`, `buildCommandArgs`). - **R4 — Save context and spelling (P1):** HTTP save CEL reads `body` and `saved_placeholder`; command save CEL reads `output` and the currently implemented misspelling `saved_palceholder`. Validate response field names and casing. Reference: `action.go` (`HTTPRequestAction.doSavePlaceholder`, `CommandAction.doSavePlaceholder`) and [PR #105](https://github.com/tidbcloud/APITestGen/pull/105). - **R5 — Retry budget (P2):** Total attempts are `max_retries + 1`; retry delay is `delay_after`, and saves happen only after a successful attempt. Calculate the delay budget as `max_retries * delay_after`. Reject zero-delay retry storms and review budgets over 1,800 seconds. Reference: `action.go` (`HTTPRequestAction.Do`, `CommandAction.Do`). - **R6 — Continued failures and dependencies (P1):** `continue_on_unexpected: true` lets later steps run after failure, but response/output placeholders are not saved. Do not let downstream steps consume values produced only by a continued failing step. Reference: `Scenario_suite_test.go` (`Test_001_ExecuteActions`) and `action.go` (`Do`). - **R7 — Cluster placeholder cleanup (P1):** Teardown treats every placeholder key beginning with `cluster` as a cluster ID. Save real cluster IDs as `cluster_1`, `cluster_2`, and avoid that prefix for endpoints, ports, users, or unrelated resources. Reference: `Scenario_suite_test.go` (`clearClusters`). - **R8 — Auth object safety (P1):** Every HTTP step must provide an auth object compatible with its auth type. Digest auth without `auth_role` requires non-null `content`; hardcoded public/private keys require security review. Reference: `actionbuilder.go` (`buildHTTPClient`, `BuildAction`). ## Historical defect rules - **H1 — CEL validity and meaning (P1):** Check operators, parentheses, field existence, collection access safety, and boolean result type. A missing `&&` caused a compile-time failure in [PR #102](https://github.com/tidbcloud/APITestGen/pull/102#discussion_r2501921565). - **H2 — Provider consistency (P1):** Keep provider, region, bucket scheme, cloud identity, request fields, and expected values consistent. An AliCloud case retained an AWS region in [PR #104](https://github.com/tidbcloud/APITestGen/pull/104#discussion_r2502942557), while the same fix changed `s3://`/AWS ARN values to `oss://`/ACS RAM values. - **H3 — Representation and field casing (P1):** Align `Accept` headers with CEL/save response paths and apply the representation choice to every affected operation and provider variant. References: [PR #105](https://github.com/tidbcloud/APITestGen/pull/105), [PR #219](https://github.com/tidbcloud/APITestGen/pull/219), and [PR #223](https://github.com/tidbcloud/APITestGen/pull/223). - **H4 — Verify operation-specific status codes (P1):** Do not copy an expectation from a superficially similar operation. Confirm protected auto-backup deletion versus manual-backup deletion and other state-dependent errors. References: [PR #180 review](https://github.com/tidbcloud/APITestGen/pull/180#discussion_r3007324256) and [PR #208](https://github.com/tidbcloud/APITestGen/pull/208). - **H5 — Poll readiness before mutation or connection (P2):** API resource state may become ready before SQL/network endpoints do. Poll the exact readiness signal before scaling, deleting, or connecting. References: [PR #114](https://github.com/tidbcloud/APITestGen/pull/114) and [PR #217](https://github.com/tidbcloud/APITestGen/pull/217). - **H6 — Complete and asynchronous cleanup (P1/P2):** Ensure every created resource has cleanup and retry parent cleanup while child deletion is asynchronous. References: [PR #166](https://github.com/tidbcloud/APITestGen/pull/166) and [PR #170](https://github.com/tidbcloud/APITestGen/pull/170). - **H7 — Scope list/readiness checks (P2):** Filter collection requests to the resource created by this scenario when unrelated tenant resources can affect results. Reference: [PR #218](https://github.com/tidbcloud/APITestGen/pull/218). - **H8 — Parameterize credentials (P0):** Replace hardcoded access keys and secrets with existing runner placeholders and workflow secrets. Reference: [PR #214](https://github.com/tidbcloud/APITestGen/pull/214). - **H9 — Cross-variant and diff-scope consistency (P2/P3):** Compare equivalent AWS, GCP, Azure, and AliCloud cases when a shared API contract changes. Ensure the stated review scope matches every changed YAML. Reference: [PR #223 scope review](https://github.com/tidbcloud/APITestGen/pull/223#discussion_r3577688733).