Document the web dashboard feature

[oleiade]

What?

This PR aims to document the web dashboard feature that lands in v0.49.0 of k6.

I've been struggling somewhat to put this together, and I'd really like as much input, suggestions and feedback as possible as to how to structure this, the amount of detail we want to provide, as well as where it should live.

@szkiba I would especially love your input on this too 👍

Checklist

Please fill in this template:

• I have used a meaningful title for the PR.
• I have described the changes I've made in the "What?" section above.
• I have performed a self-review of my changes.
• I have run the make docs command locally and verified that the changes look good.
• I have made my changes in the docs/sources/next folder of the documentation.

[szkiba]

K6_WEB_DASHBOARD_REPORT_FILENAME should be change to K6_WEB_DASHBOARD_EXPORT

[szkiba]

Perhaps a sentence could be written about how the report can be automatically saved using the K6_WEB_DASHBOARD_EXPORT environment variable, without starting a browser.

[heitortsergent]

@oleiade I think this is really good, thanks for writing this up!

I made some suggestions for changing the order of the sections and the headings, and some suggestions related to our Grafana style guide. :)

I think the location of the page makes sense, we could also add a mention of it to the "Results output" page under the Get started section. Maybe as a new heading right above the "Time series and external outputs" section: https://grafana.com/docs/k6/latest/get-started/results-output/#time-series-and-external-outputs

Two questions I have:

• Would it make sense to have some sort of admonition at the top and point people to the xk6-dashboard repository if people want to give feedback on the dashboard?

• I saw this section on the xk6-dashboard README, and I'm wondering if we should include it as well?

  "The k6 process waits to exit as long as there is at least one open browser window for the dashboard extension. In this way, the report can be downloaded, for example, even after the test has been completed.

  In certain environments, it is not allowed that the k6 process does not exit after the test run (eg CI/CD pipeline). In this case, it is advisable to disable the HTTP port (with the -1 value of port parameter)."

[heitortsergent]

I think we should move this section above the "HTML test reports" one, so it goes: Introduction, How to use, HTML reports, Dashboard options.

[heitortsergent]

@oleiade thanks for making the updates!

I think we can get this merged if you want and make improvements later on. :)

I'd still like to move the "How to use" section up, and I left a suggestion for how we can mention the K6_WEB_DASHBOARD_EXPORT variable.

@szkiba I don't know if you saw my comment, but are the warnings we have on the xk6-dashboard Usage section still applicable here? If they are, I think it would make sense to mention it in the docs as well.