---
name: use-scenario-e2e-framework
description: Explain and operate the APITestGen TiDB Cloud scenario E2E framework across scenario YAML, the tidb-management-service Go runner, and GitHub Actions. Use when onboarding to the framework; tracing how a scenario runs; locating framework code; choosing or writing a new scenario test; configuring local runner parameters or non-secret workflow dispatch on a secret-backed workflow contract; validating locally or in GHA; understanding placeholders, retries, CEL, auth, result persistence, or teardown; or troubleshooting scenario workflow failures.
---

# Use the TiDB Cloud Scenario E2E Framework

Answer framework questions and guide changes from repository evidence. Treat `scenario_testcases/*.yaml` in APITestGen as the reusable scenario source and `tidbcloud/tidb-management-service` as the runner/workflow implementation.

## Establish ground truth

1. Work from the APITestGen repository root.
2. Run `git status --short`, `git log -1 --oneline`, `git show -1 --stat`, and `git diff --stat`. Preserve unrelated changes.
3. Read [README.md](../../README.md) before authoring or debugging scenario YAML.
4. Resolve runner evidence from `$TIDB_MANAGEMENT_SERVICE_DIR` when set, then an available `../tidb-management-service` checkout, then the pinned official source recorded in the references. Never require a sibling checkout. When current-main behavior is material, compare it with the pinned revision.
5. Do not infer endpoints, fields, status codes, auth behavior, response shapes, cloud commands, or asynchronous states. Verify them from current API definitions, runner code, workflow code, or concrete runtime evidence.

## Route the task

- For architecture, execution flow, runner behavior, configuration, GHA integration, cleanup, or failure diagnosis, read [execution-and-architecture.md](references/execution-and-architecture.md).
- For writing a scenario, selecting an existing template, static checks, Go compilation, local replay, or GHA validation, read [authoring-and-validation.md](references/authoring-and-validation.md).
- For exact local environment variables, safe config templates, GitHub Actions inputs, or non-secret REST/CLI dispatch on a repaired secret-backed workflow, read [runtime-configuration.md](references/runtime-configuration.md).
- For broad onboarding, read all three references before answering.

## Use the authoring and review skills

For a new or changed test, use the narrower project skills instead of reproducing their workflows:

1. Explicitly load and follow `skills/write-scenario-yaml/SKILL.md` to design or edit the case from explicit API/CLI evidence.
2. Explicitly load and follow `skills/review-scenario-yaml/SKILL.md` after editing.
3. Run the deterministic checker named by the review skill before any live execution.

Use existing YAML only as a runner-compatible template and historical example. Do not treat it as sufficient proof of an unfamiliar API contract.

## Keep validation claims precise

Distinguish these outcomes:

- **Static validation:** YAML, embedded JSON objects, request type, order, placeholder binding, retry, limited structural checks, and exact patterns for AWS access-key IDs, GitHub tokens, and private-key PEM blocks. It does not call TiDB Cloud and is not a general secret scanner.
- **Compile validation:** the Go runner package compiles. It does not parse or execute the selected scenario.
- **Local replay:** the Go suite executes live HTTP/CLI actions and may create, mutate, or delete cloud resources.
- **GHA validation:** a selected workflow prepares the matrix and environment, fetches the YAML, executes the Go suite, and publishes JUnit results.

Never claim a scenario passed end to end from static or compile validation alone. State the exact file, command or workflow, result, and any unexecuted level.

## Protect credentials and resources

- Never commit API keys, account tokens, passwords, DSNs, cloud credentials, SAS tokens, or fixed tenant resources.
- Use a non-production test tenant and disposable resources for live validation unless production execution is explicitly authorized.
- Review cleanup before running. Automatic teardown targets placeholders whose keys start with `cluster`, but other provider resources generally require explicit scenario cleanup.
- Do not set `skip_tear_down` merely to bypass a failing cleanup path.