Add a section for Login examples

[immavalls]

Based on the older https://stackoverflow.com/questions/69016260/is-there-any-way-to-rerun-the-setup-step-every-few-minutes-in-a-long-duration-te I was thinking we could provide an example similar to https://community.k6.io/t/caching-access-tokens/5508/3. To showcase what happens if the authorization token has a short expiration.

Add what we need to do to update the token being used by that VU if a request returns a 403, to continue the iterations. I've seen some users having doubts that they could do that.

What can't be done is update the token for all VUs. However, if each VU gets its own token, we can also update it if it expires.

Would that be a useful example? If not we can just close this issue. Opening for feedback.

[immavalls]

Another example https://community.k6.io/t/unique-login-for-each-virtual-user/5563/9, in this case not of a token that expires. Though it seems it's not super clear to some users how to get a token for each user.

[ppcano]

Login, data parametrization, and correlation and dynamic data is one of the most common cases and where many new users struggle with.

I suggest handling this issue holistically: review current examples, add new ones, improve structure, add common pitfalls, etc.

Is there more doc issues related to this one?

[immavalls]

Thanks @ppcano I'll review the forums for older similar topics and we can figure out if a tutorial or blog can help with a more complete example. Maybe separate APIs from websites (httpx sessions can help here as well).

[immavalls]

Another example that is trying to get the cookies under setup() https://community.k6.io/t/handling-cookies-from-setup-function-to-default-function/5817/3

[immavalls]

I'm repurposing this to discuss where we could fit a section/tutorial that helps users with login options. Maybe something similar to https://k6.io/blog/ways-to-visualize-k6-results/ for login.

• API
  • Login with user/password to get a token and reuse the token (all VUs with the same token, or each VU its token)
  • Token that can expire after a while, so mid-iterations we have to get a new token.
  • Examples: how to test services that require auth when the auth itself is not what you're looking to test #339
• Websites
  • Login and get the cookies for subsequent requests
  • Other headers that are needed via dynamic correlation

etc.

[MattDodsonEnglish]

Nice issue. Here's my thoughts about the structure and information flow. In short, I think we have two things two do:

• Add more content in the blog tutorial, examples, or both
• Link information together, where the API doc connects to example and the examples connect to the tutorial, and reverse

Also, no need to overthink it. Anything we do that addresses common, real questions will fill an information gap. If it's useful, we'll find a place and format for it :-)

Example vs. blog tutorial

I don't think this is an either/or situation. For short workflows, we can add an example. For longer, step-by-step procedures, a tutorial works better. In both cases, it's nice to provide context of a plausible case from real life and use examples that can be reproduced on a local machine.

We also don't have any nested sidebar sections in the examples page, but I don't see why we couldn't. For example "Login and authentication." (Not recommending anything specific).

The main difference is that a tutorial proceeds from one logical step to another. The reader should be able to follow along and learn by doing. An example is more "grab and go"; it assumes the reader will more or less know what to do.

For the tutorial, I think the Grafana Tutorial template is totally fine.

For an example, this seems like a good starting structure:

# <title> Refresh token 

<example_of_real_life_problem>
On some tests, the authentication token expires after a certain amount of time.
If your load test has a long duration, you need to refresh your token to make sure that your VUs run into expected, but unintended behavior. For example, the server may return 403s.

<overview_of_functionality_with_links>
This example refreshes a token in this procedure
1. Call [Foo](/api-doc) to initialize the tokenizer.
2. Use the tokenizer to call the [time-police](/API-doc) to reset the clock.

//Code with comments

In both forms, it's probably good to avoid explanation. These should be fast to read and overexplanation drags the pace down. Ideally we should have a separate conceptual doc of any important concepts. Let the introductory sentences of the procedure be the explanation itself.

Don't take that structure so seriously. You might see a more logical way. Let the information and document goal tell you what to do :-) .

Linking things together

This is maybe something we need to be more mindful about. In all of these examples, I think the information more or less already exists in the docs, but they require too much inference from the reader. So whenever we add a tutorial, or example we should link to it from other relevant docs and vice versa. This will create a "connective tissue" throughout the docs to enforce the relationships between general functionality and specific solutions.

I think the docs more or less have the information, but it requires readers to figure too much out. Having some explicit examples could really save work, not only for readers but also for us in reducing repetitive support queries.

Don't overthink it

I think I typed too much.

[immavalls]

This is another example of a user asking how to manage expiring tokens during test, that we can add https://community.k6.io/t/calling-token-api-every-hour/5881

[immavalls]

Another example when needing to refresh a token: https://community.k6.io/t/generated-token-every-10-mins-and-use-it-during-load-test/5978

[immavalls]

Yet another example https://stackoverflow.com/questions/75588705/how-to-implement-once-only-controller-in-k6/75590121#75590121

[immavalls]

We'll do some examples in the docs to solve this.

[immavalls]

Another example from the forums: https://community.k6.io/t/cant-update-variable-in-default-function/6987. I will check if it makes sense to open a feature request to make this scenario more integrated with k6 somehow.