GitHub - bxrne/dstest: Test the **** out of containers. Deterministic Simulation Testing for containerised services.

Deterministic Simulation Testing for containerised services.

Write Lua scripts to define, control, and verify chaos experiments on Docker containers with reproducible fault injection.

Workload generation, walkable fault trees and benefit of the LuaJIT std lib.

Installation

From crates.io:

cargo install dstest

# Run a script file
dstest < examples/oracle.lua

# Or use REPL mode: type your script interactively, press Ctrl+D to execute
dstest

Or build from source:

git clone https://github.com/bxrne/dstest
cd dstest
cargo build --release

Quick Start

# Run a script file
cat examples/oracle.lua | cargo run

# Or use REPL mode: type your script and press Ctrl+D to run it
cargo run

Overview

dstest lets you write Lua scripts that define test subjects (Docker containers), inject faults (pause, kill, resource deprivation, proxied network impairments), and verify service resilience: including virtual clocks for time-dependent logic, seeded workload randomness, depends for multi-service startup ordering, and sustained workload generation from OpenAPI specs.

Important

Deterministic Execution & Workloads While fault selection and schedule generation are seed-deterministic, standard container execution under default runtimes (runc) is subject to OS process/thread scheduling variance and wall-clock timing jitter. To make container execution and workload timing fully deterministic across runs, subjects must be configured with the dtrun OCI runtime:

local s = dstest.setup(cfg, {
    image = "my-service:latest",
    runtime = "dtrun", -- Enables deterministic execution via dtrun
    ports = { 8080 },
})

Examples

oracle.lua - Fault injection with oracle predicates and invariants
link.lua - Proxied network faults: latency, loss, partitions between subjects
pg.lua - PostgreSQL: connect, create table, insert, query, close

Documentation

See DOCS.md for the full Lua API reference.

AI Assistant Support

This repo includes an AI skill (SKILL.md) that teaches assistants how to work with dstest.

To use with your agent:

# Claude Code / Opencode
cp SKILL.md ~/.config/opencode/skills/dstest/SKILL.md

# Other agents (e.g., ~/.agents/skills/)
mkdir -p ~/.agents/skills/dstest
cp SKILL.md ~/.agents/skills/dstest/SKILL.md

Then instruct your assistant to "use the dstest skill" when writing or debugging chaos experiments.

Requirements

A Docker-compatible daemon reachable over DOCKER_HOST (Docker or Podman with DOCKER_HOST pointed at the Podman socket; docker may be aliased to podman)
Rust 1.85+ (uses 2024 edition)

License

MIT