dstest 0.1.6

Deterministic Simulation Testing for containerised services
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

# subs

Subject introspection — container state, logs, and command execution. Exposes
`dstest.inspect`, `dstest.logs`, `dstest.exec` (flat on the `dstest` table).

## `dstest.inspect(subject)`

Returns container metadata and runtime state.

```lua
local info = dstest.inspect(subject)
assert(info.state == "running", "container should be running")
```

| Field | Type | Description |
|-------|------|-------------|
| `state` | string | `"running"`, `"paused"`, `"exited"`, or `"dead"` |
| `pid` | number? | Process ID |
| `ip` | string? | Container IP address |
| `memory_limit` | number? | Memory limit in bytes |
| `cpu_quota` | number? | CPU quota (0.0-1.0) |

## `dstest.logs(subject, options?)`

Fetches container logs. Returns an array of log entries.

```lua
local logs = dstest.logs(subject, { tail = "50", timestamps = true })
for _, entry in ipairs(logs) do
    if entry.stream == "stderr" then
        dstest.warn(entry.message)
    end
end
```

### Options

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `stdout` | boolean | `true` | Include stdout stream |
| `stderr` | boolean | `true` | Include stderr stream |
| `tail` | string | `"all"` | Number of lines (`"50"`, `"all"`) |
| `since` | number | - | UNIX timestamp (seconds) |
| `timestamps` | boolean | `false` | Include timestamps |

### Entry shape

| Field | Type | Description |
|-------|------|-------------|
| `stream` | string | `"stdout"` or `"stderr"` |
| `message` | string | Log line content |

## `dstest.exec(subject, command)`

Runs a command inside the container and returns the result.

```lua
local result = dstest.exec(subject, {"ls", "-la", "/app"})
if result.exit_code == 0 then
    dstest.info("files:\n" .. result.stdout)
else
    dstest.error("exec failed: " .. result.stderr)
end
```

| Field | Type | Description |
|-------|------|-------------|
| `exit_code` | number | Exit code (`-1` if unknown) |
| `stdout` | string | Standard output |
| `stderr` | string | Standard error |