avh4 / avh4/elm-program-test

Improve documentation for simulateHttpResponseAdvanced

Open
#164 0 comments 0 reactions 0 assignees View on GitHub
documentation good first issue semver: patch
Dominant language
Elm
Stars
95
Forks
28
PR merge metrics
No merged PRs in 30d

Description

People don't understand what the `Int` parameter means.

My explanation answering a slack thread:

> it’s the index of which request in the queue for that method/URL to handle, so if you have 4 to the same method/URL that are all still pending, then you can choose 1, 2, 3, or 4 as the one to resolve.
> Note that if you made multiple of those requests at the same moment (in the same batch of effects), then there might be little trial and error to figure out what order they got put into the queue in.
> Also note that you only need that if the simultaneous requests were made to the same URL and HTTP method. If they were all to different URLs and/or methods, then you can just use the normal `simulateHttpResponse`

Also, when a request is resolved, it's no longer in the queue, so if you had 4 and resolved one of them, then there would only be 3 immediately after.

Also, it's safe to use the normal `simulateHttpResponse` if you're unsure, since the error message will tell you if you need to use `simulateHttpResponseAdvanced`.

It would probably be good to explain an example of one or more scenarios.

The goals for the docs here should be:
- Make it clear when you _don't_ need `simulateHttpResponseAdvanced` (and what to prefer instead)
- Clearly explain how to use it when needed
- Be as concise as possible while fulfilling the other goals.

Contributor guide

Open the contributing guide

Research direction

Start by locating the documentation for simulateHttpResponseAdvanced and compare it with simulateHttpResponse. Explain what the Int queue index selects, when the advanced helper is needed, how resolved requests change the queue, and include a concise example showing the expected usage.

Written by the indexing model from the issue text.

Assessment

Tech stack
elm
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.