# E2E Test Case Layout

E2E cases under `tests/test-cases` are split into two groups based on how many
runtime configurations need to execute them:

- `default-only/`
  - These tests run only once, under the `default` configuration.
  - Use this group for small-data test cases that validate basic write, read,
    or index behavior.
  - If a test is not expected to trigger multiple shards, readers, or workers,
    it belongs here.
- `multi-config/`
  - These tests run under all four configurations:
    `default`, `multi-readers`, `multi-shards`, and `multi-workers`.
  - Use this group for large-data test cases, or for tests that explicitly rely
    on multi-shard, multi-reader, or multi-worker behavior.
  - [sample.test](/DATA/disk1/jinhelin/tici-ci/tests/test-cases/multi-config/sample.test)
    is the current reference example for this group.

## Adding a new test

When adding a new `.test` file, first decide whether it really needs coverage
under multiple configurations:

- Default to `default-only/`.
- Put a test into `multi-config/` only if at least one of the following is true:
  - It writes enough data to potentially trigger shard splitting.
  - Its assertions depend on reading from multiple shards.
  - Its assertions depend on multiple readers or multiple workers.
  - The issue being covered only reproduces under `multi-readers`,
    `multi-shards`, or `multi-workers`.

If a test only validates normal query behavior with a small amount of data, do
not place it in `multi-config/`, because that slows down the full e2e matrix
without adding coverage.

## Migrating endless FTS cases

Only migrate SQL-only cases into this directory. A migrated case must be
deterministic, small enough for merge CI, and expressible with the transcript
directives supported by `tests/tools/test_runner.py`.

Do not migrate cases that require expected SQL errors, session-pinned state,
transactions across directives, prepared statements, fault injection,
benchtoolset, external S3/KS3 datasets, BR, Lightning, sysbench, TiFlash, or
long-running health checks.

Use `wait> shard_progress table=test.<table> index=<index>` after DML that must
be visible to an FTS assertion. Prefer `default-only/` unless the case explicitly
requires multi-reader, multi-worker, or multi-shard behavior.