[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6ACDEEZV2HYP1FHPCM20NTM":3,"skill-same:01M6ACDEEZV2HYP1FHPCM20NTM":77},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":43,"linkOnly":44,"markdownContent":45,"markdownBody":46,"frontMatter":47,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":51,"repositoryHtmlUrl":52,"repositoryHomepageUrl":53,"ownerHtmlUrl":54,"ownerBlogUrl":55,"ownerDescription":6,"updatedAt":56,"install":57,"resources":70},"01M6ACDEEZV2HYP1FHPCM20NTM","seatunnel-test-suite",null,"Write or review Apache SeaTunnel E2E (Testcontainers) and unit tests so they are stable, leak-free, and deterministic. Use when creating a new *IT\u002F*Test class, reviewing a test diff, or refactoring a flaky or leaking test.","apache\u002Fseatunnel","apache","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F47359?v=4","01M6AC83E6K4FDKK7HZ8WNMQKE","The Apache Software Foundation","01M6ACD7F18WKGBBAAMFNATJ23",9805,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fapache\u002Fseatunnel\u002Fblob\u002Fdev\u002F.skills\u002Fseatunnel-test-suite\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",[24,25,26,27,9,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"test","suite","test suite","seatunnel test suite","e2e","refactoring","write","use","diff","unit tests","deterministic","tests","free","unit","it","testcontainers","review","when","new","2026-11-10 10:12:30",false,"---\nname: seatunnel-test-suite\ndescription: Write or review Apache SeaTunnel E2E (Testcontainers) and unit tests so they are stable, leak-free, and deterministic. Use when creating a new *IT\u002F*Test class, reviewing a test diff, or refactoring a flaky or leaking test.\n---\n\n# SeaTunnel Test Suite\n\nSelf-contained operating manual for writing and reviewing SeaTunnel tests: the rule tables, citable IDs, and\nthe patterns needed to act. Everything required to apply or cite a rule is in this file.\n\n## When to use\n\n- Writing a new connector E2E test (`*IT.java`) or unit test (`*Test.java`).\n- Reviewing a test diff for flakiness, leaks, or layout violations before a PR.\n- Stabilizing a flaky or leaking test, or bringing an older test up to these conventions.\n\n## Framework contract (E2E)\n\nEvery E2E test **must** follow this structural contract — violating it means the test silently does nothing.\n\n| Requirement | Detail |\n|-------------|--------|\n| Extend `TestSuiteBase` | Provides the engine container lifecycle, `NETWORK`, and test dispatch |\n| `@TestInstance(Lifecycle.PER_CLASS)` | Inherited from `TestSuiteBase` — one instance shared across all methods; fields need not be `static` |\n| `@TestTemplate` on each test method | NOT `@Test`. The `TestCaseInvocationContextProvider` only dispatches `@TestTemplate` methods |\n| `TestContainer` parameter | Each `@TestTemplate` method must accept a single `TestContainer container` parameter |\n| `@DisabledOnContainer` (optional) | Add **only** when the scenario genuinely can't run on an engine — see below. Default to no annotation so the test runs on all engines. |\n\nMinimal skeleton — runs on every engine (Zeta, Flink, Spark), which is the default and correct case for\nmost batch source\u002Fsink tests:\n\n```java\npublic class MyConnectorIT extends TestSuiteBase {\n\n    @TestTemplate\n    public void testSourceToSink(TestContainer container) throws Exception {\n        Container.ExecResult result = container.executeJob(\"\u002Fmy_connector_to_assert.conf\");\n        Assertions.assertEquals(0, result.getExitCode());\n    }\n}\n```\n\n### When to add `@DisabledOnContainer`\n\nDo not exclude an engine by default. Add the annotation only when a scenario provably cannot run on that\nengine, and word `disabledReason` for the *specific* scenario — not a blanket \"engine X is unsupported\".\nThe exclusion can go on the class (whole suite) or a single `@TestTemplate` method (just that case). Real\nreasons from the codebase:\n\n| Excluded engines | Why (the real constraint) |\n|------------------|---------------------------|\n| Spark | CDC \u002F streaming jobs — Spark doesn't support the continuous\u002Fchangelog mode |\n| Spark + Flink | checkpoint-restore tests; scenarios needing Zeta-only features |\n| Spark + Flink (all but Zeta) | continuous-discovery long-running jobs; SeaTunnel-only behavior |\n| Spark | drops the RowKind of a record, so changelog assertions fail |\n\n```java\n\u002F\u002F Only this CDC case can't run on Spark — exclude at the method, not the class:\n@TestTemplate\n@DisabledOnContainer(\n        value = {},\n        type = {EngineType.SPARK},\n        disabledReason = \"Spark does not support the CDC streaming job\")\npublic void testCdcStreaming(TestContainer container) throws Exception {\n    \u002F\u002F ...\n}\n```\n\n## The rules\n\nTwo namespaces: **E1–E7 govern E2E (`*IT`) tests** (cite as `[E3]`); **U1–U6 govern unit (`*Test`)\ntests** (cite as `[U5]`). E6 is Zeta-engine-only. Pick the namespace that matches the file under review —\nnever apply an E-rule to a unit test or vice versa.\n\n| # | Rule | Check (the smell) | Fix |\n|---|------|-------------------|-----|\n| E1 | Dynamic ports | literal `127.0.0.1:\u003Cport>` \u002F `localhost:\u003Cport>` in Java code | `container.getHost()` + `container.getMappedPort(p)`; `.conf` files reference the network alias + internal port (see E7) |\n| E2 | Condition-based waiting | any `Thread.sleep(...)` | `Awaitility.await().atMost(...).pollInterval(...).untilAsserted(...)`; timeout from the scenario table below |\n| E3 | Release resources | an opened client\u002Fconnection\u002Fcontainer with no close | implement `TestResource`, close in `tearDown()` reverse-order + null-safe; try-with-resources for method-scoped |\n| E4 | Async job submission | inline `executeJob` for a streaming\u002FCDC job (never returns) | `CompletableFuture.supplyAsync(...)`, gate on `RUNNING`, act, verify, `cancel(true)` |\n| E5 | Share one container | a fresh container started per test method | share one container across all methods in a class (`@TestInstance(PER_CLASS)`) |\n| E5b | Pin image versions | `:latest` image tag | pin a specific version, e.g. `mysql:8.0.32`, never `mysql:latest` (see subsection) |\n| E5c | Cover all data types | only `String`\u002F`int` exercised | cover the connector's full data-type set, not just the easy ones |\n| E6 | Thread whitelist (Zeta) | `There are still threads running in the container` | close the client first (E3); if the lib thread is unrecyclable, whitelist its prefix in `isIssueWeAlreadyKnow(...)` |\n| E7 | Docker network | container not reachable from engine container | `.withNetwork(NETWORK).withNetworkAliases(\"my-alias\")`; start with `Startables.deepStart(...)`; add `Slf4jLogConsumer(DockerLoggerFactory.getLogger(IMAGE))` for debug logs (full setup below) |\n\n### E7 — network setup\n\nThe SeaTunnel engine runs **inside** its own Docker container. External service containers must share the\nsame Docker network so the engine can reach them (this is also why E1's `.conf` files use the alias, not the\nmapped host port). Setup pattern:\n\n```java\n\u002F\u002F In your IT class @BeforeAll (NETWORK is inherited from TestSuiteBase):\ncontainer = new GenericContainer\u003C>(DockerImageName.parse(\"my-service:1.2.3\"))\n        .withNetwork(NETWORK)                            \u002F\u002F inherited field from TestSuiteBase\n        .withNetworkAliases(\"my-service-host\")           \u002F\u002F reachable by this name from engine\n        .withExposedPorts(3306)\n        .withLogConsumer(new Slf4jLogConsumer(DockerLoggerFactory.getLogger(\"my-service:1.2.3\")));\nStartables.deepStart(Stream.of(container)).join();       \u002F\u002F parallel startup\n```\n\nIn your `.conf` file (runs inside the engine container):\n```hocon\nhost = \"my-service-host\"\nport = 3306\n```\n\nIn your Java test setup (runs on the host):\n```java\nString jdbcUrl = String.format(\"jdbc:mysql:\u002F\u002F%s:%d\u002Ftest\",\n        container.getHost(), container.getMappedPort(3306));\n```\n\n### E2 — timeout reference\n\n| Scenario | atMost | pollInterval |\n|----------|--------|--------------|\n| Container \u002F client readiness | 2 min | 1 s |\n| Job reaches `RUNNING` | 1 min | 2 s |\n| Batch job result verified | 60 s | 2 s |\n| MQ \u002F Kafka consumption | 30–60 s | 1 s |\n| CDC \u002F schema-change propagation | 60–120 s | 2–5 s |\n\nChain `.ignoreExceptions()` onto the `Awaitility.await()` (the E2 fix) whenever the client throws until the\nservice is up — otherwise the first poll's exception fails the wait instead of retrying. Never pick a bare\nround number without a scenario to justify it.\n\n### E5b — image version pinning\n\nNever use `:latest` — upstream images can change behavior without warning, breaking CI with no code diff to\nbisect. Pin to a specific minor or patch version:\n\n```java\n\u002F\u002F Bad — breaks unpredictably\nprivate static final String IMAGE = \"postgres:latest\";\n\n\u002F\u002F Good — reproducible\nprivate static final String IMAGE = \"postgres:14.5\";\n```\n\n### E6 — thread whitelist, in one paragraph\n\nAfter the last job finishes, `SeaTunnelContainer` snapshots the server JVM and fails if a non-system thread\nsurvives 120s. Daemon threads from third-party clients (JDBC drivers, HTTP pools) are sometimes unrecyclable.\nFor those only, add a **specific name prefix** to `isIssueWeAlreadyKnow(String)` in `SeaTunnelContainer`, with\na comment naming the library. A thread you *can* close belongs in `tearDown()`, not the whitelist. System\nthreads (`hz.main`, `pool-N-thread-N`, …) are already handled by `isSystemThread(...)` — don't duplicate them.\n\n### UT rules\n\nUse this table for `*Test` classes (Surefire, no engine container):\n\n| # | Rule | Smell | Fix |\n|---|------|-------|-----|\n| U1 | Test behavior, not internals | asserts on private fields or internal call order | assert observable output\u002Fstate; verify `void` calls only when side-effect IS the contract |\n| U2 | No timing or IO dependence | `Thread.sleep`, `System.currentTimeMillis()`, filesystem, network | remove timing; mock\u002Ffake IO boundaries; inject clocks if needed |\n| U3 | Mock at boundaries only | mocking domain objects or `new`-able value types | only mock external interfaces\u002Fclients\u002Fmaps\u002Fservices the class depends on via constructor or setter |\n| U4 | One behavior per method | multi-branch `if`\u002F`for` inside a single test | split into one method per branch; name each method as the behavior it proves |\n| U5 | Negative paths assert message | `assertThrows(FooException.class, ...)` with no message check | also call `assertThat(ex.getMessage()).contains(\"expected fragment\")` |\n| U6 | Naming | `testFoo`, `testBar`, `test123` | class `*Test`; methods like `shouldReturn404WhenUserMissing`, `throwsOnNullHost` |\n\n**Mock setup shape** — each test method is Arrange-Act-Assert:\n1. *Arrange* — in `@BeforeEach`, `mock(...)` every external boundary, wire the chain with `when(...).thenReturn(...)`, then construct the SUT. Per test, stub only the values that select the branch under test.\n2. *Act* — call the one method under test.\n3. *Assert* — check observable output (U1), not call chains.\n\nPitfalls that make a mocked test pass for the wrong reason:\n- When the SUT reaches a collaborator through a chain (`a.getB().getC(key)`), stub the whole chain, and stub each lookup with the *exact* key constant the production code uses — a mismatched key returns `null` and silently changes the branch taken.\n- To exercise a downstream branch, stub every upstream guard non-null first; a null upstream value short-circuits early, so stubbing only the downstream value tests nothing.\n- For negative paths, assert the exception message fragment, not just the type (U5) — a wrong-cause throw of the same type would otherwise pass.\n\n**When NOT to mock:**\n- Simple value objects, POJOs, DTOs — use real instances.\n- The class under test itself — never mock the SUT.\n- When an in-memory fake (e.g. `HashMap` instead of an interface) is simpler and equally isolated.\n\n## Layout (where things go)\n\nOne Maven module per connector under `seatunnel-e2e\u002Fseatunnel-connector-v2-e2e\u002Fconnector-\u003Cname>-e2e\u002F`. Files\nload from the test **classpath root** (`src\u002Ftest\u002Fresources\u002F`):\n\n- Test class → `src\u002Ftest\u002Fjava\u002Forg\u002Fapache\u002Fseatunnel\u002Fe2e\u002Fconnector\u002F\u003Cname>\u002F\u003CName>IT.java`\n  (CDC connectors use the `...connectors.seatunnel.cdc.\u003Cname>` package). `*IT` = integration (Failsafe),\n  `*Test` = unit (Surefire).\n- Job configs → `src\u002Ftest\u002Fresources\u002F\u003Cname>_source_to_sink.conf`, referenced with a **leading slash**\n  (`executeJob(\"\u002F\u003Cname>_source_to_sink.conf\")`). License header required (`#` comments).\n- DDL → `src\u002Ftest\u002Fresources\u002Fddl\u002F\u003Ctable>.sql` (CDC `UniqueDatabase` resolves `ddl\u002F\u003Ctemplate>.sql`).\n- Container mounts → `src\u002Ftest\u002Fresources\u002Fdocker\u002F...`, referenced via the container API (no leading slash).\n- Register the module in the parent `pom.xml`; for a new connector also update CI label and\n  `plugin-mapping.properties`.\n\n## Review workflow\n\n1. Grep for the obvious smells (a clean result is a hint, not a guarantee — `127\\.0\\.0\\.1` and `localhost`\n   are also matched without a port to catch host references where the port is templated separately):\n   ```bash\n   grep -nE \"Thread\\.sleep|127\\.0\\.0\\.1|localhost|:latest\" \u003Ctest-file>\n   ```\n2. **[E1, E7]** External containers joined to `NETWORK` with aliases? `.conf` uses alias + internal port?\n3. **Framework contract:** extends `TestSuiteBase`? `@TestTemplate` + `TestContainer` param (not `@Test`)?\n4. **`@DisabledOnContainer`** — present only where a scenario truly can't run on an engine (no blanket exclusions), and scoped to the affected method when only one case is incompatible?\n5. **[E3]** Each opened resource closed in `tearDown()` (or try-with-resources)? Container stopped explicitly?\n6. **[E4]** Streaming\u002FCDC jobs submitted via `CompletableFuture.supplyAsync` and gated on `RUNNING`?\n7. **[E2]** Timeouts justified by the scenario table — no bare round numbers?\n8. **[E5, E5b, E5c]** One container shared per class? Image versions pinned (no `:latest`)? Full type set?\n9. Resources in the conventional paths; new module registered in the parent pom?\n10. **[E6]** For Zeta E2E, run the full job set; if the thread-leak check fires, close the client first.\n11. For unit tests, walk the **[U1–U6]** table; for the negative path confirm **[U5]** asserts the message.\n12. Run the targeted test class multiple times to confirm stability:\n    ```bash\n    .\u002Fmvnw -pl seatunnel-e2e\u002Fseatunnel-connector-v2-e2e\u002Fconnector-\u003Cname>-e2e \\\n        -DskipUT -DskipIT=false -Dit.test=\u003CITClassName> verify\n    ```\n\n## Quick-fix reference\n\nEach row cites the rule it enforces, so a quick-fix finding maps directly to the output format below.\n\n| Rule | Smell | Replace with |\n|------|-------|--------------|\n| E2 | `Thread.sleep(n)` then assert | `Awaitility.await().atMost(...).untilAsserted(...)` |\n| E1 | `\"tcp:\u002F\u002Flocalhost:61616\"` | `container.getHost() + \":\" + container.getMappedPort(61616)` |\n| E3 | missing `tearDown()` | implement `TestResource`; null-safe, reverse-order close + `container.stop()` |\n| E4 | inline `executeJob` for a streaming job | `CompletableFuture.supplyAsync(...)` + gate on `RUNNING` |\n| E4 | `consumer.receive()` with no timeout | `consumer.receive(timeoutMs)` or Awaitility poll |\n| E4 | swallowed exception in async block | rethrow as `CompletionException` |\n| E6 | Zeta E2E fails on leftover client thread | close in `tearDown()`; if unrecyclable, whitelist in `isIssueWeAlreadyKnow` |\n| — | `@Test` on E2E method | change to `@TestTemplate` + add `TestContainer container` parameter |\n| E5b | `postgres:latest` | `postgres:14.5` (pin to specific version) |\n| E7 | container unreachable from engine | `.withNetwork(NETWORK).withNetworkAliases(\"...\")` |\n| U5 | `assertThrows(...)` with no message check | add `assertTrue(ex.getMessage().contains(\"...\"))` |\n\n## Output format\n\nWhen reviewing, report each finding as `[\u003CRuleId>] \u003Cfile>:\u003Cline> — \u003Cissue>` with a one-line fix, where\n`\u003CRuleId>` is an E-rule (`E1`–`E7`) for `*IT` tests or a U-rule (`U1`–`U6`) for `*Test` units — e.g.\n`[E3] FooIT.java:88 — Kafka consumer never closed`. Show a before\u002Fafter snippet only when the fix isn't\nobvious from the rule. When writing a new class, satisfy all applicable rules and add the Apache License\nheader to every new file (including `.conf` and `.sql`).\n","# SeaTunnel Test Suite\n\nSelf-contained operating manual for writing and reviewing SeaTunnel tests: the rule tables, citable IDs, and\nthe patterns needed to act. Everything required to apply or cite a rule is in this file.\n\n## When to use\n\n- Writing a new connector E2E test (`*IT.java`) or unit test (`*Test.java`).\n- Reviewing a test diff for flakiness, leaks, or layout violations before a PR.\n- Stabilizing a flaky or leaking test, or bringing an older test up to these conventions.\n\n## Framework contract (E2E)\n\nEvery E2E test **must** follow this structural contract — violating it means the test silently does nothing.\n\n| Requirement | Detail |\n|-------------|--------|\n| Extend `TestSuiteBase` | Provides the engine container lifecycle, `NETWORK`, and test dispatch |\n| `@TestInstance(Lifecycle.PER_CLASS)` | Inherited from `TestSuiteBase` — one instance shared across all methods; fields need not be `static` |\n| `@TestTemplate` on each test method | NOT `@Test`. The `TestCaseInvocationContextProvider` only dispatches `@TestTemplate` methods |\n| `TestContainer` parameter | Each `@TestTemplate` method must accept a single `TestContainer container` parameter |\n| `@DisabledOnContainer` (optional) | Add **only** when the scenario genuinely can't run on an engine — see below. Default to no annotation so the test runs on all engines. |\n\nMinimal skeleton — runs on every engine (Zeta, Flink, Spark), which is the default and correct case for\nmost batch source\u002Fsink tests:\n\n```java\npublic class MyConnectorIT extends TestSuiteBase {\n\n    @TestTemplate\n    public void testSourceToSink(TestContainer container) throws Exception {\n        Container.ExecResult result = container.executeJob(\"\u002Fmy_connector_to_assert.conf\");\n        Assertions.assertEquals(0, result.getExitCode());\n    }\n}\n```\n\n### When to add `@DisabledOnContainer`\n\nDo not exclude an engine by default. Add the annotation only when a scenario provably cannot run on that\nengine, and word `disabledReason` for the *specific* scenario — not a blanket \"engine X is unsupported\".\nThe exclusion can go on the class (whole suite) or a single `@TestTemplate` method (just that case). Real\nreasons from the codebase:\n\n| Excluded engines | Why (the real constraint) |\n|------------------|---------------------------|\n| Spark | CDC \u002F streaming jobs — Spark doesn't support the continuous\u002Fchangelog mode |\n| Spark + Flink | checkpoint-restore tests; scenarios needing Zeta-only features |\n| Spark + Flink (all but Zeta) | continuous-discovery long-running jobs; SeaTunnel-only behavior |\n| Spark | drops the RowKind of a record, so changelog assertions fail |\n\n```java\n\u002F\u002F Only this CDC case can't run on Spark — exclude at the method, not the class:\n@TestTemplate\n@DisabledOnContainer(\n        value = {},\n        type = {EngineType.SPARK},\n        disabledReason = \"Spark does not support the CDC streaming job\")\npublic void testCdcStreaming(TestContainer container) throws Exception {\n    \u002F\u002F ...\n}\n```\n\n## The rules\n\nTwo namespaces: **E1–E7 govern E2E (`*IT`) tests** (cite as `[E3]`); **U1–U6 govern unit (`*Test`)\ntests** (cite as `[U5]`). E6 is Zeta-engine-only. Pick the namespace that matches the file under review —\nnever apply an E-rule to a unit test or vice versa.\n\n| # | Rule | Check (the smell) | Fix |\n|---|------|-------------------|-----|\n| E1 | Dynamic ports | literal `127.0.0.1:\u003Cport>` \u002F `localhost:\u003Cport>` in Java code | `container.getHost()` + `container.getMappedPort(p)`; `.conf` files reference the network alias + internal port (see E7) |\n| E2 | Condition-based waiting | any `Thread.sleep(...)` | `Awaitility.await().atMost(...).pollInterval(...).untilAsserted(...)`; timeout from the scenario table below |\n| E3 | Release resources | an opened client\u002Fconnection\u002Fcontainer with no close | implement `TestResource`, close in `tearDown()` reverse-order + null-safe; try-with-resources for method-scoped |\n| E4 | Async job submission | inline `executeJob` for a streaming\u002FCDC job (never returns) | `CompletableFuture.supplyAsync(...)`, gate on `RUNNING`, act, verify, `cancel(true)` |\n| E5 | Share one container | a fresh container started per test method | share one container across all methods in a class (`@TestInstance(PER_CLASS)`) |\n| E5b | Pin image versions | `:latest` image tag | pin a specific version, e.g. `mysql:8.0.32`, never `mysql:latest` (see subsection) |\n| E5c | Cover all data types | only `String`\u002F`int` exercised | cover the connector's full data-type set, not just the easy ones |\n| E6 | Thread whitelist (Zeta) | `There are still threads running in the container` | close the client first (E3); if the lib thread is unrecyclable, whitelist its prefix in `isIssueWeAlreadyKnow(...)` |\n| E7 | Docker network | container not reachable from engine container | `.withNetwork(NETWORK).withNetworkAliases(\"my-alias\")`; start with `Startables.deepStart(...)`; add `Slf4jLogConsumer(DockerLoggerFactory.getLogger(IMAGE))` for debug logs (full setup below) |\n\n### E7 — network setup\n\nThe SeaTunnel engine runs **inside** its own Docker container. External service containers must share the\nsame Docker network so the engine can reach them (this is also why E1's `.conf` files use the alias, not the\nmapped host port). Setup pattern:\n\n```java\n\u002F\u002F In your IT class @BeforeAll (NETWORK is inherited from TestSuiteBase):\ncontainer = new GenericContainer\u003C>(DockerImageName.parse(\"my-service:1.2.3\"))\n        .withNetwork(NETWORK)                            \u002F\u002F inherited field from TestSuiteBase\n        .withNetworkAliases(\"my-service-host\")           \u002F\u002F reachable by this name from engine\n        .withExposedPorts(3306)\n        .withLogConsumer(new Slf4jLogConsumer(DockerLoggerFactory.getLogger(\"my-service:1.2.3\")));\nStartables.deepStart(Stream.of(container)).join();       \u002F\u002F parallel startup\n```\n\nIn your `.conf` file (runs inside the engine container):\n```hocon\nhost = \"my-service-host\"\nport = 3306\n```\n\nIn your Java test setup (runs on the host):\n```java\nString jdbcUrl = String.format(\"jdbc:mysql:\u002F\u002F%s:%d\u002Ftest\",\n        container.getHost(), container.getMappedPort(3306));\n```\n\n### E2 — timeout reference\n\n| Scenario | atMost | pollInterval |\n|----------|--------|--------------|\n| Container \u002F client readiness | 2 min | 1 s |\n| Job reaches `RUNNING` | 1 min | 2 s |\n| Batch job result verified | 60 s | 2 s |\n| MQ \u002F Kafka consumption | 30–60 s | 1 s |\n| CDC \u002F schema-change propagation | 60–120 s | 2–5 s |\n\nChain `.ignoreExceptions()` onto the `Awaitility.await()` (the E2 fix) whenever the client throws until the\nservice is up — otherwise the first poll's exception fails the wait instead of retrying. Never pick a bare\nround number without a scenario to justify it.\n\n### E5b — image version pinning\n\nNever use `:latest` — upstream images can change behavior without warning, breaking CI with no code diff to\nbisect. Pin to a specific minor or patch version:\n\n```java\n\u002F\u002F Bad — breaks unpredictably\nprivate static final String IMAGE = \"postgres:latest\";\n\n\u002F\u002F Good — reproducible\nprivate static final String IMAGE = \"postgres:14.5\";\n```\n\n### E6 — thread whitelist, in one paragraph\n\nAfter the last job finishes, `SeaTunnelContainer` snapshots the server JVM and fails if a non-system thread\nsurvives 120s. Daemon threads from third-party clients (JDBC drivers, HTTP pools) are sometimes unrecyclable.\nFor those only, add a **specific name prefix** to `isIssueWeAlreadyKnow(String)` in `SeaTunnelContainer`, with\na comment naming the library. A thread you *can* close belongs in `tearDown()`, not the whitelist. System\nthreads (`hz.main`, `pool-N-thread-N`, …) are already handled by `isSystemThread(...)` — don't duplicate them.\n\n### UT rules\n\nUse this table for `*Test` classes (Surefire, no engine container):\n\n| # | Rule | Smell | Fix |\n|---|------|-------|-----|\n| U1 | Test behavior, not internals | asserts on private fields or internal call order | assert observable output\u002Fstate; verify `void` calls only when side-effect IS the contract |\n| U2 | No timing or IO dependence | `Thread.sleep`, `System.currentTimeMillis()`, filesystem, network | remove timing; mock\u002Ffake IO boundaries; inject clocks if needed |\n| U3 | Mock at boundaries only | mocking domain objects or `new`-able value types | only mock external interfaces\u002Fclients\u002Fmaps\u002Fservices the class depends on via constructor or setter |\n| U4 | One behavior per method | multi-branch `if`\u002F`for` inside a single test | split into one method per branch; name each method as the behavior it proves |\n| U5 | Negative paths assert message | `assertThrows(FooException.class, ...)` with no message check | also call `assertThat(ex.getMessage()).contains(\"expected fragment\")` |\n| U6 | Naming | `testFoo`, `testBar`, `test123` | class `*Test`; methods like `shouldReturn404WhenUserMissing`, `throwsOnNullHost` |\n\n**Mock setup shape** — each test method is Arrange-Act-Assert:\n1. *Arrange* — in `@BeforeEach`, `mock(...)` every external boundary, wire the chain with `when(...).thenReturn(...)`, then construct the SUT. Per test, stub only the values that select the branch under test.\n2. *Act* — call the one method under test.\n3. *Assert* — check observable output (U1), not call chains.\n\nPitfalls that make a mocked test pass for the wrong reason:\n- When the SUT reaches a collaborator through a chain (`a.getB().getC(key)`), stub the whole chain, and stub each lookup with the *exact* key constant the production code uses — a mismatched key returns `null` and silently changes the branch taken.\n- To exercise a downstream branch, stub every upstream guard non-null first; a null upstream value short-circuits early, so stubbing only the downstream value tests nothing.\n- For negative paths, assert the exception message fragment, not just the type (U5) — a wrong-cause throw of the same type would otherwise pass.\n\n**When NOT to mock:**\n- Simple value objects, POJOs, DTOs — use real instances.\n- The class under test itself — never mock the SUT.\n- When an in-memory fake (e.g. `HashMap` instead of an interface) is simpler and equally isolated.\n\n## Layout (where things go)\n\nOne Maven module per connector under `seatunnel-e2e\u002Fseatunnel-connector-v2-e2e\u002Fconnector-\u003Cname>-e2e\u002F`. Files\nload from the test **classpath root** (`src\u002Ftest\u002Fresources\u002F`):\n\n- Test class → `src\u002Ftest\u002Fjava\u002Forg\u002Fapache\u002Fseatunnel\u002Fe2e\u002Fconnector\u002F\u003Cname>\u002F\u003CName>IT.java`\n  (CDC connectors use the `...connectors.seatunnel.cdc.\u003Cname>` package). `*IT` = integration (Failsafe),\n  `*Test` = unit (Surefire).\n- Job configs → `src\u002Ftest\u002Fresources\u002F\u003Cname>_source_to_sink.conf`, referenced with a **leading slash**\n  (`executeJob(\"\u002F\u003Cname>_source_to_sink.conf\")`). License header required (`#` comments).\n- DDL → `src\u002Ftest\u002Fresources\u002Fddl\u002F\u003Ctable>.sql` (CDC `UniqueDatabase` resolves `ddl\u002F\u003Ctemplate>.sql`).\n- Container mounts → `src\u002Ftest\u002Fresources\u002Fdocker\u002F...`, referenced via the container API (no leading slash).\n- Register the module in the parent `pom.xml`; for a new connector also update CI label and\n  `plugin-mapping.properties`.\n\n## Review workflow\n\n1. Grep for the obvious smells (a clean result is a hint, not a guarantee — `127\\.0\\.0\\.1` and `localhost`\n   are also matched without a port to catch host references where the port is templated separately):\n   ```bash\n   grep -nE \"Thread\\.sleep|127\\.0\\.0\\.1|localhost|:latest\" \u003Ctest-file>\n   ```\n2. **[E1, E7]** External containers joined to `NETWORK` with aliases? `.conf` uses alias + internal port?\n3. **Framework contract:** extends `TestSuiteBase`? `@TestTemplate` + `TestContainer` param (not `@Test`)?\n4. **`@DisabledOnContainer`** — present only where a scenario truly can't run on an engine (no blanket exclusions), and scoped to the affected method when only one case is incompatible?\n5. **[E3]** Each opened resource closed in `tearDown()` (or try-with-resources)? Container stopped explicitly?\n6. **[E4]** Streaming\u002FCDC jobs submitted via `CompletableFuture.supplyAsync` and gated on `RUNNING`?\n7. **[E2]** Timeouts justified by the scenario table — no bare round numbers?\n8. **[E5, E5b, E5c]** One container shared per class? Image versions pinned (no `:latest`)? Full type set?\n9. Resources in the conventional paths; new module registered in the parent pom?\n10. **[E6]** For Zeta E2E, run the full job set; if the thread-leak check fires, close the client first.\n11. For unit tests, walk the **[U1–U6]** table; for the negative path confirm **[U5]** asserts the message.\n12. Run the targeted test class multiple times to confirm stability:\n    ```bash\n    .\u002Fmvnw -pl seatunnel-e2e\u002Fseatunnel-connector-v2-e2e\u002Fconnector-\u003Cname>-e2e \\\n        -DskipUT -DskipIT=false -Dit.test=\u003CITClassName> verify\n    ```\n\n## Quick-fix reference\n\nEach row cites the rule it enforces, so a quick-fix finding maps directly to the output format below.\n\n| Rule | Smell | Replace with |\n|------|-------|--------------|\n| E2 | `Thread.sleep(n)` then assert | `Awaitility.await().atMost(...).untilAsserted(...)` |\n| E1 | `\"tcp:\u002F\u002Flocalhost:61616\"` | `container.getHost() + \":\" + container.getMappedPort(61616)` |\n| E3 | missing `tearDown()` | implement `TestResource`; null-safe, reverse-order close + `container.stop()` |\n| E4 | inline `executeJob` for a streaming job | `CompletableFuture.supplyAsync(...)` + gate on `RUNNING` |\n| E4 | `consumer.receive()` with no timeout | `consumer.receive(timeoutMs)` or Awaitility poll |\n| E4 | swallowed exception in async block | rethrow as `CompletionException` |\n| E6 | Zeta E2E fails on leftover client thread | close in `tearDown()`; if unrecyclable, whitelist in `isIssueWeAlreadyKnow` |\n| — | `@Test` on E2E method | change to `@TestTemplate` + add `TestContainer container` parameter |\n| E5b | `postgres:latest` | `postgres:14.5` (pin to specific version) |\n| E7 | container unreachable from engine | `.withNetwork(NETWORK).withNetworkAliases(\"...\")` |\n| U5 | `assertThrows(...)` with no message check | add `assertTrue(ex.getMessage().contains(\"...\"))` |\n\n## Output format\n\nWhen reviewing, report each finding as `[\u003CRuleId>] \u003Cfile>:\u003Cline> — \u003Cissue>` with a one-line fix, where\n`\u003CRuleId>` is an E-rule (`E1`–`E7`) for `*IT` tests or a U-rule (`U1`–`U6`) for `*Test` units — e.g.\n`[E3] FooIT.java:88 — Kafka consumer never closed`. Show a before\u002Fafter snippet only when the fix isn't\nobvious from the rule. When writing a new class, satisfy all applicable rules and add the Apache License\nheader to every new file (including `.conf` and `.sql`).\n",{"name":5,"description":7},"dev","fcb404cd947da03a712c4ae9ee9068744bd946a5",".skills\u002Fseatunnel-test-suite",2466,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fseatunnel","https:\u002F\u002Fseatunnel.apache.org\u002F","https:\u002F\u002Fgithub.com\u002Fapache","https:\u002F\u002Fwww.apache.org\u002F","2026-11-14 18:13:47",{"source":8,"skillName":5,"commands":58,"prompt":68,"zipAvailable":69},[59,62,65],{"tool":60,"command":61},"npx","npx skills add apache\u002Fseatunnel --skill seatunnel-test-suite",{"tool":63,"command":64},"bunx","bunx skills add apache\u002Fseatunnel --skill seatunnel-test-suite",{"tool":66,"command":67},"pnpm","pnpm dlx skills add apache\u002Fseatunnel --skill seatunnel-test-suite","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fapache\u002Fseatunnel\u002Fblob\u002Fdev\u002F.skills\u002Fseatunnel-test-suite\u002FSKILL.md",true,[71],{"path":72,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":75,"sourceHtmlUrl":76},"agents\u002Fopenai.yaml","REFERENCE","参考文档",1034,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fseatunnel\u002Fblob\u002Fdev\u002F.skills\u002Fseatunnel-test-suite\u002Fagents\u002Fopenai.yaml",[78],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":43},"01M6ACDASAHBX4RK9JQPPHJQ95","seatunnel-pr-submit","Draft or submit Apache SeaTunnel pull requests in English using the repository's required title and body conventions. Use when Codex needs to prepare a PR from the current branch or diff, infer a compliant `[Type][Module][SubModule] Description` title, fill the required PR template, describe what changed from git history or file diffs, or open the PR after the user provides or omits the change summary.","https:\u002F\u002Fgithub.com\u002Fapache\u002Fseatunnel\u002Fblob\u002Fdev\u002F.skills\u002Fseatunnel-pr-submit\u002FSKILL.md",[],[85,86,87,88,89,41,90,91,92,93,94,95,96,97,98,9,99,100,101,102,103,104],"pr","submit","pr submit","seatunnel pr submit","open","describe","body","title","english","infer","branch","template","diffs","repository","pull","git","prepare","change","pull requests","codex"]