docs: profiles use-case guide — define behaviors, switch at runtime - #97
Merged
Conversation
docs/profiles.md, linked from the README profiles section: six verified recipes for the scenarios real APIs won't give you on demand — chaos testing at an exact rate (chance + rng_seed), revoked credentials as a switch (pre-dispatch 401), the one broken customer (when.expr on the request), hanging vs slow dependencies (behavior:timeout / latency_ms), adapter-authored degraded modes (profile_active, sqs-style throttled), and flipping worlds between test cases in CI. Every YAML block assembles into a manifest that passes stunt plan; every transcript is real output from a live run (429-pattern under chance:30, 401 invalid_api_key, 201/402 expr split, 200 in 1.50s, curl(52) hang at 700ms, 'activated "throttled" on sqs').
Healthy GET /v1/charges is 200 (201 is the POST create); the one-broken- customer curls carry the auth header (without it the fall-through 401s, not 201); preset fragment notes that every set: name must be a declared service.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Profiles are documented as a reference (schema, semantics) but not as a tool: the
README says what the knobs are, not what you build with them. This adds the use-case
guide the feature deserves — the scenarios that are hard or impossible to get from
real APIs on demand.
What —
docs/profiles.md, six recipeschance: 30under a fixedrng_seed: thesame 4-of-12 failures every run, so retry/backoff tuning becomes a unit test.
adapter's auth sees it; no waiting an hour for token expiry.
when.expronrequest.body.amount > 1000: thesurgical failure shape real sandboxes never expose.
behavior: timeout(circuit-breaker food) vslatency_ms-only slow-success (timeout budgets, SLA UX).throttledpattern:profile_active()in the handler, including the state-backed-counter caveat.CI,
up --profile, the dashboard panel,--json.Plus the fine print (precedence, WS/GraphQL, determinism, name resolution) and the
three shapes a profile can take up front.
Verification
stunt plan(this caughta real drafting error: rule bundles shown under the top-level
profiles:key —that's the preset namespace; they belong on the service).
chance: 30,401 {"error":"invalid_api_key"}, the 201/402 expr split,200 in 1.501475s,curl: (52)at the 700 ms hang,activated "throttled" on sqs.Linked from the README's Profiles section and the Reference list.