Simulated TMS Connector: Code Lab to Tender and Track Autonomous Vehicles

Hook — Why your integration tests for autonomous trucks probably fail

If you work on TMS integrations, autonomous fleet software, or telemetry pipelines, you know the pain: tests that pass locally but break in staging, flaky dispatch flows, and gaps between tendering semantics in your TMS and the vehicle control stack. You need repeatable, fast, realistic integration tests that emulate tendering, dispatch and tracking of autonomous trucks — without waiting for a live AV fleet or expensive vendor sandboxes.

This code lab gives you a practical starter kit: a Simulated TMS Connector — a mock TMS API, an autonomous-truck simulator that emits telemetry, a ClickHouse-backed telemetry store, and a set of integration test patterns you can run in CI. By the end you'll have a local environment to validate end-to-end flows: tender → assign → dispatch → telemetry → reconciliation.

The context in 2026 (why build this now)

Late 2025 and early 2026 accelerated adoption of TMS-autonomous truck integrations. Industry leaders shipped first-of-kind links connecting driverless fleets into TMS platforms — enabling tendering and dispatch by shippers and brokers from their existing TMS dashboards. At the same time, OLAP databases like ClickHouse gained traction as telemetry backends for time-series and analytical workloads after major funding and product improvements in late 2025 and early 2026.

“Seamless tendering, dispatching and tracking of autonomous trucks through TMS platforms is moving from pilot to scale — and that creates a testing gap you must fill.”

Those two trends make this simulator relevant: teams need pragmatic, reproducible tools to validate the operational contract between a TMS and an AV stack. This lab focuses on realistic behaviors (latency, retries, network blips), and on analytical verification using ClickHouse for telemetry queries in integration tests.

What you’ll get in this code lab

• Mock TMS API to create tenders, view status, and assign vehicles.
• Autonomous truck simulator that emulates routing and emits telemetry (GPS, speed, heading, battery).
• Telemetry ingestion into ClickHouse for fast analytical queries used in assertions.
• Example integration tests (pytest + requests) that run in CI.
• Load test script (k6) and patterns to simulate hundred+ trucks for stress testing.

High-level architecture

Keep the architecture minimal for rapid iteration, but realistic enough for production-like behaviour:

• Mock TMS API (HTTP REST) — accepts tenders, returns candidate assignments, stores state.
• Dispatcher — an event loop or service that assigns tenders to vehicles based on capacity/ETA rules.
• Vehicle Simulator — lightweight processes or containers that simulate trucks and send telemetry to an ingestion endpoint.
• Telemetry Ingest — HTTP endpoint or Kafka connector that writes to ClickHouse.
• ClickHouse — OLAP store used for tracking queries and integration assertions.
• CI — test runner that exercises the full loop and queries ClickHouse to verify outcomes.

Quickstart: run the simulator locally (Docker Compose)

Clone the starter repo (replace with your chosen URL) and run compose. The compose file brings up:

• mock-tms (Node/Express)
• sim-vehicle (Python asyncio)
• clickhouse-server
• clickhouse-client (for convenience)

docker-compose up --build
# then open http://localhost:8080/docs for mock TMS API docs
  

Essential Mock TMS endpoints

Design the mock API to match the contract you expect from production TMS. Example endpoints:

• POST /tenders — create a tender. Returns tenderId and desired pickup/dropoff.
• GET /tenders/{id} — check tender status (open / assigned / in_transit / completed / failed).
• POST /tenders/{id}/assign — request assignment to a vehicle (vehicleId optional).
• GET /vehicles — list simulated vehicles and status.
• POST /vehicles/{id}/command — send dispatch command (start/pause/stop/reroute).

Minimal Node/Express mock TMS (snippet)

const express = require('express');
const app = express();
app.use(express.json());
let tenders = {};
let id = 1;
app.post('/tenders', (req, res) => {
  const tid = `T${id++}`;
  tenders[tid] = { id: tid, status: 'open', ...req.body };
  res.status(201).json(tenders[tid]);
});
app.get('/tenders/:id', (req,res)=> res.json(tenders[req.params.id]||{}));
// assign, list vehicles... (elided)
app.listen(8080);

Vehicle simulator: telemetry and state machine

Each simulated truck runs a tiny state machine: idle → assigned → enroute → unloading → complete. While enroute, it emits telemetry at a configurable frequency to the ingest endpoint. Use asyncio or Node for simplicity.

Telemetry payload (JSON)

{
  "vehicleId": "V123",
  "tenderId": "T42",
  "ts": "2026-01-18T12:00:00Z",
  "lat": 40.7128,
  "lon": -74.0060,
  "speedKph": 55.3,
  "heading": 84,
  "batteryPercent": 82.1
}

Emit telemetry every 1–5 seconds in functional tests; for load testing reduce to 10–30s or batch up events.

Ingesting telemetry into ClickHouse

ClickHouse is well-suited to store high-volume telemetry for analytical queries and to support integration assertions (e.g., “vehicle reached geofence within expected time”). Create a compact, partitioned table optimized for insert speed and query patterns.

Recommended schema

CREATE TABLE telemetry (
  event_time DateTime64(3) ,
  vehicle_id String,
  tender_id String,
  lat Float64,
  lon Float64,
  speed_kph Float32,
  heading UInt16,
  battery Float32
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(event_time)
ORDER BY (vehicle_id, event_time);

Use HTTP endpoint or Kafka connector to write to ClickHouse. For CI tests, the HTTP INSERT INTO ... VALUES method is simplest. Keep retention policies to control cost in long-running test clusters.

Example integration test flow

1. Reset test DB state (truncate tables in ClickHouse).
2. Create a tender via POST /tenders (mock TMS).
3. Verify tender appears in TMS as open.
4. Trigger dispatch: POST /tenders/{id}/assign (dispatcher sim will push command to vehicle).
5. Simulated vehicle updates status to enroute and starts emitting telemetry.
6. Wait and assert via ClickHouse that telemetry points exist for tender_id and vehicle_id and that vehicle entered defined geofence within X minutes.
7. Assert final status in mock TMS is completed.

pytest snippet: assert telemetry arrived

def test_tender_to_completion(clickhouse_client, requests_session):
    r = requests_session.post('http://localhost:8080/tenders', json=payload)
    tid = r.json()['id']
    # assign
    requests_session.post(f'http://localhost:8080/tenders/{tid}/assign')
    # poll clickhouse for telemetry
    for _ in range(30):
        rows = clickhouse_client.execute("SELECT count() FROM telemetry WHERE tender_id = %(t)s", {'t': tid})
        if rows[0][0] > 0:
            break
        time.sleep(1)
    assert rows[0][0] > 0

Load and chaos testing patterns

Beyond correctness, test scale and resilience. Use k6 for HTTP traffic and a fleet generator to spawn many simulator instances. Inject chaos:

• Network latency and packet loss between TMS and vehicle (tc/netem in containers).
• Delayed telemetry (buffer and replay).
• Duplicate messages and idempotency checks for POST /tenders/{id}/assign.
• Clock skew — simulate vehicle clocks drift and verify server-side ordering by timestamps.

Advanced integration checks (practical examples)

Use ClickHouse analytical queries to make richer assertions in tests:

• Verify route compliance: count telemetry points inside a polygon (geofence) before/after timestamp.
• Compute median arrival time for 95th percentile SLA checks (use GROUP BY and quantile functions).
• Detect telemetry gaps using window functions (identify stalls > N seconds).

-- Example: 95th percentile time to geofence entry per route
SELECT quantileExact(0.95)(toUnixTimestamp(event_time) - toUnixTimestamp(assign_time)) AS p95
FROM telemetry JOIN tenders USING (tender_id)
WHERE tender_id = 'T42' AND is_in_geofence(lat, lon) = 1

(Note: create helper functions or approximate geofence checks via bounding boxes for performance.)

Handling real-world edge cases

Autonomous systems are messy. Simulate and test these failure modes:

• Partial acceptance: vehicle accepts tender but later releases due to hardware fault. Validate automatic re-tendering logic.
• Split loads: a tender may be split between vehicles — test partial completion and reconciliation.
• Intermittent telemetry: design reconciliation to handle intermittent telemetrics without marking runs as failed prematurely.
• Security: ensure tokens expire, check re-auth flows, and simulate compromised vehicle keys in test mode.

CI integration — reproducible tests

Use ephemeral ClickHouse instances in CI (testcontainers) or a shared staging ClickHouse with isolated partitions per run. Key practices:

• Run tests inside containers orchestrated by Docker or GitHub Actions services.
• Truncate telemetry tables between tests or use unique tenant prefixes (tenant_id column).
• Fail fast: if dispatch never occurs within a threshold, capture logs and dump telemetry snapshots for debugging.
• Use contract tests (Pact) for the TMS↔AV API surface so both sides can evolve safely.

Storage, retention and cost considerations with ClickHouse

Telemetry can explode. ClickHouse is fast but plan for retention and aggregation:

• Raw telemetry: short retention (days-weeks) depending on test needs.
• Downsampled aggregates: hourly/5m rollups for long-term analytics.
• Use TTL clauses in ClickHouse to automatically expire raw rows and move aggregates to cheaper storage.

Security & data privacy

Telemetry may include sensitive location data. For test environments:

• Mask or use synthetic geographies when running outside controlled networks.
• Use short-lived credentials and mutual TLS for transport in production-like tests.
• Keep PII out of telemetry; if required for tests, use synthetic IDs and disposable credentials.

Developer experience tips

Make the simulator approachable to increase adoption:

• Provide a single CLI to start: start-sim --vehicles 10 --freq 2s --profile urban
• Include OpenAPI docs for the mock TMS so tests can generate clients automatically.
• Ship a set of pre-configured scenarios: happy-path, reroute-failure, high-latency, split-loads.
• Offer test fixtures and helpers for ClickHouse queries to assert telemetry conditions.

Case study: local team shortened test cycles by 70%

One freight-software team (anonymous) integrated a similar simulator in late 2025. They reported:

• 70% reduction in time to reproduce TMS→vehicle failures.
• Faster onboarding of partner AV stacks using the mock API and Pact contracts.
• Ability to run nightly SLA regressions against 200 virtual trucks with k6 + simulated telemetry into ClickHouse.

Future-proofing your simulator (2026–2028)

As integrations move to production, expect:

• Standardized AV-TMS data contracts (schema registries & protobufs) — adopt them early.
• More OLAP/real-time hybrid stores: ClickHouse will stay popular for telemetry, but also evaluate streaming SQL layers for real-time reconciliation.
• Increasing regulatory telemetry retention and audit requirements — build test modes to validate compliance flows.

Actionable checklist to get started (10–30 minutes)

1. Clone the repo and run docker-compose up.
2. Create a tender via curl: POST /tenders → note tenderId.
3. Start 1–5 vehicle simulators: they should auto-register with mock TMS.
4. Assign tender and watch telemetry stream into ClickHouse (use clickhouse-client).
5. Run the provided pytest integration and examine failures.

Example curl commands

# create tender
curl -s -X POST http://localhost:8080/tenders -H 'Content-Type: application/json' -d '{"pickup":{"lat":40.7,"lon":-74.0},"dropoff":{"lat":41.0,"lon":-73.5}}'

# assign
curl -s -X POST http://localhost:8080/tenders/T1/assign

Final thoughts — make testing first-class for autonomous integrations

In 2026, TMS-to-autonomous fleet integrations are becoming a production reality. That trend means teams must move beyond ad-hoc manual tests and embrace repeatable, automated integration tests that cover functional, scale and failure scenarios. A Simulated TMS Connector with ClickHouse-backed telemetry lets you validate real operational contracts fast, cheaply, and reliably.

Start small (happy-path verification), then layer chaos and scale tests. Use ClickHouse queries as assertions in CI and keep contract tests between your TMS and AV stack to prevent breaking changes.

Call to action

Ready to try the starter kit? Clone the repo, spin up the simulator, and run the integration tests. If you want the repo link, scenario templates, or a walkthrough session, join our developer community on programa.club — drop a note in the Autonomous-TMS channel and we’ll host a live code lab. Share your scenarios and help evolve a library of realistic test profiles for everyone.

Related Reading

• VMAX Model Comparison: Which of the Three New Scooters Should You Buy?
• Drafting Inclusive Changing Room Policies: Lessons from the Tribunal Ruling on Nurses’ Dignity
• Casting Is Dead — Here’s How Local Bars and Pubs Can Still Host Watch Parties
• How Mitski’s Horror-Infused Aesthetic Can Inspire Cinematic Content for Creators
• Robot Vacuum vs Robot Mop: Which Is Right for Your Kitchen?