Fault Injection

Unfault can integrate with fault to help you run quick, targeted fault injections against your app while you’re looking at a specific route or function.

The goal is not to build a perfect chaos suite on day one. It’s to make it easy to answer: “What happens if this upstream is slow/flaky/down?” while you’re still in the code.

Install the fault CLI

If fault isn’t installed, Unfault can install it for you (downloads from GitHub releases and verifies SHA256):

unfault addon install fault

Unfault installs fault to ~/.local/bin/fault. If that directory isn’t on your PATH, Unfault will print the export line you need.

Configure the app base URL

The VS Code extension needs to know where your app is listening (to build a proxy mapping):

• unfault.fault.baseUrl (default: http://127.0.0.1:8000)

This is the target Unfault will map to the local fault proxy.

Run a fault injection from VS Code

When your cursor is inside a route handler (or a function reached by one), open Unfault: Context and use the Fault Injection panel.

When you click Run:

• Unfault starts a streaming proxy with fault run --proxy "9090=<baseUrl origin>" ....
• Unfault opens a split terminal with a ready-to-edit curl http://127.0.0.1:9090/<route> command.
• The curl command is not executed automatically.

This makes the architecture explicit: your client talks to the fault proxy, and the proxy streams traffic to your app.

Note

In this streaming proxy mode, Unfault does not offer HTTP error injection templates (because the stream is opaque). Stick to network-style faults like latency, jitter, bandwidth, packet loss, and blackhole.

Generate scenario files

If you want repeatable checks, use the Generate scenario file button in the same panel.

Unfault generates one scenario suite per discovered route and saves it under:

• tests/fault/ if it exists
• otherwise test/fault/ if it exists
• otherwise it creates tests/fault/

Each file contains multiple YAML documents separated by --- (a small suite of scenarios for that route).

To run a scenario file:

fault scenario run --scenario tests/fault/post-payments.yaml

Using unfault review --llm (for agents)

When you run:

unfault review --llm

the JSON output includes a resilience testing section meant to be acted on, not skimmed.

Two fields matter in practice:

• next_steps: a short, ordered list of what to do next
• resilience_testing: an action-oriented alias of operational_healthiness (same content)

In most workflows the right sequence is:

1. Ensure the service is running locally (or ask the user to start it)
2. Generate a runnable fault run ... command from a short recipe
3. Run the generated command and drive traffic through the local proxy
4. After the run, ask whether to tear down the dev server and any test resources

Generate a fault command from a short recipe

Unfault intentionally provides a small, easy-to-use subset of fault scenarios.

List supported recipes:

unfault addon fault list

Generate a runnable fault run ... command:

unfault addon fault plan "latency 200ms for 30s" --proxy-port 9090 --target http://127.0.0.1:8000

The planner prints a concrete fault run ... command to copy/paste, plus a minimal hint for how to drive traffic through the proxy.

Note

The addon is deliberately not a mirror of the full fault CLI. If you need advanced scenarios, drop down to fault directly.

Troubleshooting

fault not found

• The VS Code extension will prompt you to install it.
• You can also set unfault.fault.executablePath if fault is not on your PATH.

Port 9090 already in use

• The fault proxy binds to 127.0.0.1:9090.
• If you rerun with a different template, Unfault stops the previous proxy before starting a new one.