Imported from Diapth/seedcmp (sections/im/WuKongIM/test/e2e/AGENTS.md). Install upstream with npx skills add Diapth/seedcmp --skill e2e. Copyright stays with the author.

test/e2e AGENTS

This file is for agents working inside the test/e2e layer. It defines the structure, execution model, and documentation maintenance rules for this directory tree.

Core Rules

• Keep this layer process-level and black-box: validate behavior through real processes, real protocols, and real public entrypoints, and do not import internal/app.
• Prefer externally observable outcomes. Do not depend on internal state, internal hooks, or test-only shortcuts.
• Do not use fixed sleeps. Prefer health checks, handshake probes, polling, and eventual-consistency assertions.
• Put reusable test support in test/e2e/suite so business assertions do not become scattered across scenario files.
• Keep failure diagnostics bounded: prefer the minimum useful config, stdout, stderr, log tails, and manager-plane responses.
• When an e2e test needs extra observability, prefer existing /manager/ APIs. If the current APIs are insufficient and a new /manager/ endpoint is required, ask the developer for confirmation before implementing it.
• When an e2e test needs large or specialized seed data, prefer adding a dedicated test-data generation API over direct store/database access. The API must be disabled by default, must only allow guest access when an explicit test mode is enabled, and should be reusable for later e2e scenarios with similar data-generation needs.

Test Data API Router Rules

• Put e2e-only data generation endpoints under the dedicated prefix /testdata/e2e; do not add them under production business routes such as /user/**, /channel/**, or /message/**.
• Use POST /testdata/e2e/<domain>/<dataset> for data generation. The <domain> segment should match the owning e2e domain when possible (cluster, message, etc.), and <dataset> should describe the reusable dataset shape, not one narrow test function.
• Return 404 or do not register the route when explicit test mode is disabled. Guest access is only allowed after that test-mode guard has passed.
• Keep route inputs in JSON request bodies, include deterministic fields such as prefix, count, seed, or payload_bytes, and make generation idempotent where practical so failed e2e runs can be retried safely.
• Add reusable client helpers for these routes in test/e2e/suite; scenario tests should call those helpers instead of constructing raw test-data URLs.

Structure Contract

• The test/e2e root should contain only shared documentation, suite/, and business-domain directories.
• Add new scenarios under test/e2e/<domain>/<scenario>/.
• Every business-domain directory must have its own AGENTS.md.
• Every scenario directory must contain its own AGENTS.md and one primary *_test.go file.
• suite/ owns reusable black-box harness code only, not scenario-specific business assertions.

Documentation Consistency

• AGENTS.md files under test/e2e are primarily for agents, not end-user README documents.
• When the e2e structure changes, the directory layout and the corresponding AGENTS.md files must stay in sync.
• When a domain or scenario is added, removed, or renamed, update the relevant AGENTS.md files in the same change.
• When a scenario's run command, core steps, or failure-diagnosis entrypoints change, update the corresponding AGENTS.md at the same time.

Running

• Full suite: go test -tags=e2e ./test/e2e/... -count=1
• For focused work, run the target scenario package directly.
• When a scenario needs custom artifact roots or node config overrides for debugging, pass test/e2e/suite options directly to StartSingleNodeCluster(...) or StartThreeNodeCluster(...).

Catalog