# Compatibility Tests

## compare.sh

Verifies 1:1 compatibility between the shell distrobox and the Go rewrite.

Uses a single image (`alpine:3.21`) — the tests compare command generation and
flag parity, not runtime behavior, so the image choice is irrelevant.

Runs two layers of comparison:
- **Dry-run**: normalizes and diffs the `docker/podman create` commands generated by both versions
- **Inspect**: creates real containers with both versions and diffs their `inspect` output (labels, env, mounts, entrypoint, security/namespace config)

### Prerequisites

- `jq`
- A container manager (`docker` or `podman`)
- Shell distrobox (the repo root scripts)
- Go binary built (`make build` from `rewrite/`)

### Usage

Run from the `rewrite/` directory:

```bash
# Autodetect container manager
./tests/compare.sh

# Explicit container manager
CONTAINER_MANAGER=docker ./tests/compare.sh

# Keep containers after test for manual inspection
./tests/compare.sh --keep

# Override paths to distrobox binaries
DISTROBOX_SHELL_PATH=/usr/bin/distrobox \
DISTROBOX_GO_PATH=./bin/distrobox \
CONTAINER_MANAGER=docker \
    ./tests/compare.sh
```

### Environment variables

| Variable | Default | Description |
|---|---|---|
| `DISTROBOX_SHELL_PATH` | `../../distrobox` (repo root) | Path to shell distrobox |
| `DISTROBOX_GO_PATH` | `./bin/distrobox` | Path to Go binary |
| `CONTAINER_MANAGER` | autodetect | `docker` or `podman` |
| `KEEP_CONTAINERS` | `0` | Set to `1` to keep containers after test |

### What gets compared

**Dry-run (no containers created):**
- Flag parity (volumes, env, labels, security opts, namespaces)
- All 2^N combinations of boolean flags (`--init`, `--unshare-netns`, `--unshare-ipc`, `--unshare-process`, `--unshare-devsys`, `--nvidia`)
- Short-flag aliases (`-d`, `-Y`, `-I`, `-ap`, etc.)
- Assemble create dry-run (basic, with options, with `--name` filtering)

**Inspect (real containers):**
- Labels
- Environment variables
- Bind mounts (source paths for distrobox scripts and unnamed docker volumes are redacted)
- Entrypoint and command args
- Security options, capabilities, PID/IPC/network namespace modes

**Flag acceptance (no dry-run available):**
- `rm`, `stop`, `generate-entry` — shell runs first as reference; if Go rejects flags shell accepts, it's a failure

### Exit codes

- `0`: all tests passed
- `1`: at least one failure; temp dir with diffs is preserved for inspection

---

## compare-docker.sh / compare-podman.sh

Convenience wrappers that run `compare.sh` with a fixed container manager.

```bash
./tests/compare-docker.sh
./tests/compare-podman.sh
```

---

## CI recommendations

- **PR gate**: run `compare-docker.sh` and `compare-podman.sh`
