AGENTS.md

1# AGENTS.md
2 
3This file adds path-specific guidance for Dumpling integration tests under
4`dumpling/tests/**`. The repository root `AGENTS.md` still applies.
5 
6## Test Placement
7 
8- Prefer extending the nearest existing case in `dumpling/tests/<case>/run.sh`
9  before adding a new case directory.
10- Keep new cases focused on one Dumpling behavior or workflow. Avoid broad
11  setup churn in shared cases unless the behavior under test needs it.
12- Use deterministic table data and exact assertions against generated files in
13  `$DUMPLING_OUTPUT_DIR`.
14- Set up and clean the database/table state needed by the test block itself.
15  Do not rely on state left by an earlier block in the same script.
16 
17## Harness Helpers
18 
19- Use `run_sql` for SQL setup and assertions against the source database.
20- Use `run_dumpling` for Dumpling invocations instead of calling `bin/dumpling`
21  directly, unless the test is specifically about the helper or command wrapper.
22- Use `file_should_exist` and `file_not_exist` for simple file presence checks.
23- Inspect dumped SQL or CSV output under `$DUMPLING_OUTPUT_DIR`; keep greps and
24  cuts narrow enough that the assertion proves the intended behavior.
25 
26## Ports and Services
27 
28- `DUMPLING_TEST_PORT=4000` targets the TiDB server started by the Dumpling test
29  harness. Use this for TiDB-specific features and TiDB version-gated behavior.
30- `DUMPLING_TEST_PORT=3306` targets the external MySQL service expected by the
31  harness. Use this only for MySQL compatibility coverage or existing cases that
32  intentionally compare MySQL behavior.
33- When a script switches ports, set `DUMPLING_TEST_PORT` explicitly before each
34  block that depends on a specific server. Do not assume the previous block left
35  the desired value.
36- If a test depends on TiDB version parsing, verify the local or CI
37  `bin/tidb-server` was built from a checkout with enough Git tag/history context
38  for `git describe --tags` to produce a semver-shaped release string. A
39  shallow or tagless checkout can make Dumpling detect TiDB as version `0.0.0`.
40 
41## Running Tests
42 
43Run commands from the repository root.
44 
45```bash
46# Build the TiDB server used by the harness when needed.
47make server
48```
49 
50```bash
51# Run every Dumpling integration case.
52make dumpling_integration_test
53```
54 
55```bash
56# Run one case.
57CASE=basic make dumpling_integration_test
58```
59 
60```bash
61# Run one case with shell tracing.
62VERBOSE=true CASE=basic make dumpling_integration_test
63```
64 
65The `dumpling_integration_test` target checks these binaries before running:
66`bin/tidb-server`, `bin/minio`, `bin/mc`, `bin/tidb-lightning`, and
67`bin/sync_diff_inspector`. The required sync-diff binary path uses an underscore:
68`bin/sync_diff_inspector`.
69 
70The full harness also expects the `mysql` client and a local MySQL-compatible
71server on `127.0.0.1:3306` for cases that target MySQL.
72 
73## Validation Notes
74 
75- For a small shell-only test change, run the changed case with
76  `CASE=<case> make dumpling_integration_test` when local prerequisites are
77  available.
78- If unrelated blocks in the same case require unavailable local services, a
79  focused TiDB-only reproduction may be useful while iterating, but report that
80  the official case target was not fully run.
81- `make bazel_prepare` is not required for changes limited to Dumpling shell
82  integration tests or this file. Re-check root `AGENTS.md` if Go files, Bazel
83  metadata, or module files are also changed.
84