|
| 1 | +<!-- |
| 2 | +
|
| 3 | + Licensed to the Apache Software Foundation (ASF) under one |
| 4 | + or more contributor license agreements. See the NOTICE file |
| 5 | + distributed with this work for additional information |
| 6 | + regarding copyright ownership. The ASF licenses this file |
| 7 | + to you under the Apache License, Version 2.0 (the |
| 8 | + "License"); you may not use this file except in compliance |
| 9 | + with the License. You may obtain a copy of the License at |
| 10 | +
|
| 11 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 12 | +
|
| 13 | + Unless required by applicable law or agreed to in writing, |
| 14 | + software distributed under the License is distributed on an |
| 15 | + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 16 | + KIND, either express or implied. See the License for the |
| 17 | + specific language governing permissions and limitations |
| 18 | + under the License. |
| 19 | +
|
| 20 | +--> |
| 21 | + |
| 22 | +# Integration Test Guidelines |
| 23 | + |
| 24 | +These instructions apply to `integration-test/` and supplement the repository-level instructions. |
| 25 | + |
| 26 | +## Credentials and deployment defaults |
| 27 | + |
| 28 | +- Use `EnvFactory.getEnv()` connection helpers or client builders with their default credentials |
| 29 | + when a test does not need a specific user. |
| 30 | +- When constructing clients or helpers that require explicit default credentials, use |
| 31 | + `SessionConfig.DEFAULT_USER` and `SessionConfig.DEFAULT_PASSWORD`. This includes |
| 32 | + `NodesSupplier`, pools, and direct RPC helpers; do not hardcode `"root"` as the default password. |
| 33 | + Default credentials can differ between IoTDB and downstream editions. |
| 34 | +- Keep a client's business connections and discovery/recovery helpers on the same credentials. |
| 35 | + Check helper methods as well as the main test body: a builder may use the correct defaults |
| 36 | + while a manually constructed discovery client silently uses different ones. |
| 37 | +- Explicit credentials are appropriate for users created by the test and for authentication or |
| 38 | + invalid-password scenarios. Make that intent clear, and clean up users created by the test. |
| 39 | +- Obtain node addresses and allocated ports from the test environment or node wrappers. Configure |
| 40 | + required consensus protocols, replication factors, and other non-default settings before |
| 41 | + initializing the cluster. |
| 42 | + |
| 43 | +## Asynchronous behavior and failure recovery |
| 44 | + |
| 45 | +- Use bounded condition waits, such as Awaitility or environment status helpers, for startup, |
| 46 | + discovery, leader election, and recovery. Prefer observable conditions over fixed sleeps. |
| 47 | +- Wait for each relevant layer separately. A node status reported by ConfigNode does not prove |
| 48 | + that an existing client has refreshed its endpoint snapshot or recovered its connection. |
| 49 | +- For locally stopped nodes, use `EnvUtils.getNodeStatusAfterLocalStop()` where applicable; |
| 50 | + graceful process termination behaves differently on Unix and Windows. Use the appropriate |
| 51 | + status expectation for forced termination. |
| 52 | +- Keep connection/socket timeouts distinct from query timeouts and the overall assertion deadline. |
| 53 | + Allow for startup and election costs on CI; use deliberately short timeouts only when needed by |
| 54 | + the scenario. Do not retry non-idempotent setup statements just to hide a short timeout. |
| 55 | +- For tests that require a stale discovery snapshot or a particular failover order, control |
| 56 | + background refresh and assert the preconditions before triggering recovery. |
| 57 | +- Investigate authentication, configuration, and transport failures before increasing a wait |
| 58 | + timeout. A retained client snapshot can mean that discovery never succeeded. Include useful |
| 59 | + endpoint/status context and preserve underlying failures when adding diagnostics. |
| 60 | +- Do not label a failure as environmental or intermittent based only on one failed run. |
| 61 | + |
| 62 | +## Isolation and assertions |
| 63 | + |
| 64 | +- Follow the neighboring tests' runner, category, and environment lifecycle conventions. Select |
| 65 | + the category matching the data model and topology required by the scenario. |
| 66 | +- Close sessions, pools, and result sets; shut down test-owned executors and clean the cluster |
| 67 | + even when assertions fail. Use try-with-resources and `finally` as appropriate. |
| 68 | +- Assert the behavior under test and its recovery result. Only tolerate expected cleanup errors |
| 69 | + in narrowly scoped cleanup code; do not swallow failures from the operation being verified. |
| 70 | + |
| 71 | +## Verification |
| 72 | + |
| 73 | +This module is excluded from the default build. Run the commands below from the repository root, |
| 74 | +always enabling `-P with-integration-tests` when building or testing this module. |
| 75 | + |
| 76 | +Format Java changes with `mvn spotless:apply -pl integration-test -P with-integration-tests`. |
| 77 | + |
| 78 | +### Targeted test runs |
| 79 | + |
| 80 | +Run only the affected IT classes or methods for a focused change. Select the matching test profile: |
| 81 | + |
| 82 | +| Data model | Default topology | Test profile | |
| 83 | +| --- | --- | --- | |
| 84 | +| Tree | 1 ConfigNode + 1 DataNode | `SimpleIT` (default) | |
| 85 | +| Tree | 1 ConfigNode + 3 DataNodes | `ClusterIT` | |
| 86 | +| Table | 1 ConfigNode + 1 DataNode | `TableSimpleIT` | |
| 87 | +| Table | 1 ConfigNode + 3 DataNodes | `TableClusterIT` | |
| 88 | + |
| 89 | +For example, run one tree-model cluster test method: |
| 90 | + |
| 91 | +```bash |
| 92 | +mvn clean verify -DskipUTs \ |
| 93 | + '-Dit.test=ClassName#methodName' \ |
| 94 | + -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false \ |
| 95 | + -pl integration-test -am -PClusterIT -P with-integration-tests |
| 96 | +``` |
| 97 | + |
| 98 | +Use `-Dit.test=ClassName` to run a whole class. Replace `-PClusterIT` with the profile needed by the |
| 99 | +test; it may be omitted for the default `SimpleIT` profile. |
| 100 | + |
| 101 | +- Check the Failsafe report to confirm that the selected test actually ran; the no-tests flags |
| 102 | + allow upstream reactor modules to have no matching tests. |
| 103 | +- Report the tested revision, edition, profile, and result accurately. Passing an upstream build |
| 104 | + does not establish that the corresponding downstream edition was tested. |
| 105 | + |
| 106 | +### Node templates and IDE runs |
| 107 | + |
| 108 | +Build the node templates before an IDE run or a direct Failsafe invocation, and rebuild them after |
| 109 | +code changes: |
| 110 | + |
| 111 | +```bash |
| 112 | +mvn clean package -DskipTests -pl integration-test -am -P with-integration-tests |
| 113 | +``` |
| 114 | + |
| 115 | +The `clean verify` command above already includes this packaging step. In IntelliJ, enable the |
| 116 | +`with-integration-tests` profile in the Maven sidebar before running test cases directly. |
| 117 | + |
| 118 | +### Edge tests |
| 119 | + |
| 120 | +Build the Edge distribution before running its dedicated Tree/Table read-write IT: |
| 121 | + |
| 122 | +```bash |
| 123 | +mvn clean package -DskipTests -pl distribution -am |
| 124 | +mvn verify -DskipUTs -Dit.test=IoTDBEdgeBasicIT \ |
| 125 | + -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false \ |
| 126 | + -pl integration-test -am -P EdgeIT -P with-integration-tests |
| 127 | +``` |
0 commit comments