Examples

Testing scenario map

Test objective	Primary decorators	Suggested script
HTTP client resilience	timeout, session_budget	examples/1_http_requests.py and examples/9_network_timeout.py
Async HTTP client	latency, jitter, packet_loss	examples/2_http_async.py
TCP protocol client	packet_reorder, packet_duplicate, half_open	examples/3_tcp_client.py
UDP protocol client	packet_loss, burst_loss, dns	examples/4_udp_client.py
Throughput testing	rate, latency, jitter	examples/8_bandwidth_throttle.py
End-to-end test run	fault, policies, reporting	examples/13_end_to_end_scenarios.py

Pattern: deterministic baseline first

Start with fixed latency or timeout before adding randomness:

import faultcore


def test_deterministic_latency_baseline() -> None:
    @faultcore.latency("50ms")
    def baseline() -> str:
        return "ok"

    assert baseline() == "ok"

Then add jitter/loss in a second scenario to isolate the source of failures.

Pattern: one fault family per test

Avoid mixing many fault types in a single test initially. Build confidence in layers:

1. Timeout-only behavior

2. Throughput-only behavior

3. Loss/reorder behavior

4. Combined scenario

Pattern: reusable policy profiles

import faultcore


def test_reusable_mobile_3g_profile_registration() -> None:
    faultcore.register_policy(name="mobile_3g", latency="150ms", jitter="40ms", packet_loss="1%", rate="2mbps")
    assert "mobile_3g" in faultcore.list_policies()

Use faultcore.fault("mobile_3g") in multiple tests to maintain consistency.

Pattern: explicit assertions

For each testing scenario, assert one primary behavior:

• timeout raised

• retry path executed

• fallback endpoint used

• total duration within expected budget

Example: HTTP client test

import faultcore


def test_http_client_profile_stack() -> None:
    @faultcore.timeout(connect="250ms", recv="800ms")
    @faultcore.packet_loss("1%")
    def call_http_api() -> dict[str, str]:
        return {"status": "ok"}

    assert call_http_api()["status"] == "ok"

Example: TCP protocol client test

import faultcore


def test_tcp_ordering_and_partial_transfer_profile() -> None:
    @faultcore.packet_reorder(prob="20%", max_delay="25ms", window=3)
    @faultcore.half_open(after="16kb", error="reset")
    def exchange_tcp_frames() -> str:
        return "ok"

    assert exchange_tcp_frames() == "ok"

Example: UDP protocol client test

import faultcore


def test_udp_loss_and_burst_profile() -> None:
    @faultcore.packet_loss("3%")
    @faultcore.burst_loss("4")
    def send_udp_datagrams() -> str:
        return "ok"

    assert send_udp_datagrams() == "ok"