Skip to content

Commit 89822fc

Browse files
Miniks040506Miniks040506
committed
docs(testing): document isolated E2E workflow
1 parent dc6d904 commit 89822fc

1 file changed

Lines changed: 126 additions & 0 deletions

File tree

‎tests/e2e/README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# VoltWeave end-to-end tests
2+
3+
This module verifies the V1 platform through the public API Gateway while using
4+
real local infrastructure and service processes. It is opt-in so a normal
5+
`mvn test` remains fast.
6+
7+
## Prerequisites
8+
9+
- JDK 21
10+
- Maven 3.9+
11+
- Docker Desktop with Linux containers
12+
- Available local CPU and memory for PostgreSQL, Keycloak, Kafka, Mosquitto and
13+
six Spring Boot processes
14+
15+
No separately installed PostgreSQL, Kafka, Keycloak or Mosquitto is required.
16+
17+
## Run from a clean checkout
18+
19+
From the repository root:
20+
21+
```powershell
22+
mvn -Pe2e verify
23+
```
24+
25+
The root reactor command is the recommended command. It builds every executable
26+
service JAR and the simulator dependency before Failsafe starts the E2E suite.
27+
28+
For a quicker rerun after those artifacts already exist:
29+
30+
```powershell
31+
mvn -pl tests/e2e -Pe2e verify
32+
```
33+
34+
Running only the module on a clean machine can fail if the service JARs or the
35+
`simulation-service` artifact have not been built yet. In that case, use the
36+
root reactor command above.
37+
38+
## Runtime lifecycle
39+
40+
`PlatformEnvironment` performs the following work for each test run:
41+
42+
1. Reserves random host ports.
43+
2. Creates a unique Docker Compose project and named volumes.
44+
3. Starts PostgreSQL/TimescaleDB, Keycloak, Kafka and Mosquitto.
45+
4. Initializes Kafka topics and Mosquitto users/ACLs.
46+
5. Starts Portfolio, Telemetry, Intelligence, Dispatch, Settlement and Gateway
47+
as child JVM processes.
48+
6. Waits for each `/actuator/health` endpoint.
49+
7. Runs the ordered platform scenarios.
50+
8. Stops child processes and removes the Compose project and volumes.
51+
52+
The suite never depends on the developer's normal Compose project or fixed
53+
host ports. A failed run preserves service logs under:
54+
55+
```text
56+
tests/e2e/target/runtime-<pid>/logs/
57+
```
58+
59+
## Covered journeys
60+
61+
The suite currently proves:
62+
63+
- Keycloak password grant for seeded admin, customer and operator users.
64+
- Organization membership, site preferences and device provisioning.
65+
- A provisioned MQTT device publishing telemetry through Kafka into the durable
66+
authorized device twin.
67+
- VPP membership, forecast baseline, flexibility snapshot, optimization preview
68+
and idempotent manual dispatch creation.
69+
- Provisioning and dispatch replay returning the original resource.
70+
- Reusing an idempotency key with a different payload returning `409 Conflict`.
71+
- Cross-tenant site isolation, role boundaries and forged JWT rejection.
72+
- Scheduled dispatch and prepared command state surviving Dispatch restarts.
73+
- Re-preparing commands after restart returning the same command IDs.
74+
75+
The dispatch is deliberately scheduled in the future. Preparing it changes the
76+
workflow to `PREPARING`, but Telemetry does not publish the MQTT command before
77+
its `validFrom`. Command ACK, timeout and rebalance transitions are covered by
78+
their focused service integration tests.
79+
80+
## Troubleshooting
81+
82+
### Missing local Maven artifact
83+
84+
If Maven reports a missing `io.voltweave:*:0.1.0-SNAPSHOT` artifact, run:
85+
86+
```powershell
87+
mvn -Pe2e verify
88+
```
89+
90+
Do not start with `-pl tests/e2e` on a clean checkout because `-pl` alone does
91+
not build sibling reactor modules.
92+
93+
### A service exits during startup
94+
95+
Open its log in the newest runtime directory:
96+
97+
```powershell
98+
$runtime = Get-ChildItem tests/e2e/target -Directory -Filter 'runtime-*' |
99+
Sort-Object LastWriteTime -Descending |
100+
Select-Object -First 1
101+
Get-Content "$($runtime.FullName)\logs\dispatch.log" -Tail 100
102+
```
103+
104+
Replace `dispatch.log` with `portfolio.log`, `telemetry.log`,
105+
`intelligence.log`, `settlement.log` or `gateway.log` as needed.
106+
107+
### Docker resources remain after an interrupted JVM
108+
109+
Normally teardown removes all resources. If the test JVM itself is killed,
110+
list projects first and remove only the exact E2E project shown:
111+
112+
```powershell
113+
docker compose ls
114+
docker compose --project-name voltweave-e2e-<pid> `
115+
--env-file tests/e2e/target/runtime-<pid>/compose.env `
116+
-f infrastructure/compose/compose.yml down --volumes --remove-orphans
117+
```
118+
119+
Never use a broad volume-prune command for this cleanup.
120+
121+
### Port or startup timeout
122+
123+
Retry once after confirming Docker Desktop is healthy. Random ports avoid the
124+
usual `8080 already in use` issue, while startup failures are reported with the
125+
last service log lines. If failures repeat, inspect the preserved logs instead
126+
of increasing timeouts first.

0 commit comments

Comments
 (0)