Fault Injection

Unfault’s LSP and VS Code extension can integrate with fault to help you run 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 answer: “What happens if this upstream is slow, flaky, or down?” while you’re still in the code.

Install the fault CLI

Install fault from its GitHub releases or directly:

# macOS
brew install fault-project/tap/fault

# Linux / manual install
curl -Lo fault https://github.com/fault-project/fault/releases/latest/download/fault-linux-x86_64
chmod +x fault && mv fault ~/.local/bin/

Configure the App Base URL

The VS Code extension needs to know where your app is listening. Set in your VS Code settings:

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

This is the target Unfault maps 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 the Unfault: Context sidebar 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 streaming proxy mode, Unfault doesn’t offer HTTP error injection templates (the stream is opaque). Stick to network-style faults: 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

Running Fault Injections

Use fault run directly for quick, targeted injections:

# Add 200ms latency for 30 seconds, proxying to your app
fault run --proxy "9090=http://127.0.0.1:8000" --latency 200ms --duration 30s

# Simulate a complete blackhole (service unreachable)
fault run --proxy "9090=http://127.0.0.1:8000" --blackhole --duration 15s

Then drive traffic through the proxy port (9090) to observe how your code handles it.

Note

The fault integration in Unfault focuses on a small, practical subset of fault scenarios. For advanced scenarios, use fault directly.

Troubleshooting

fault not found

• The VS Code extension will prompt if fault isn’t installed.
• 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.