Enable Built-in Web Dashboard by Default

[szkiba]

Feature Request: Enable Built-in Web Dashboard by Default

Is your feature request related to a problem? Please describe.

Currently, the Grafana k6 built-in web dashboard is a powerful feature for real-time test visualization, but it is disabled by default. To activate it, users must set the K6_WEB_DASHBOARD=true environment variable. This requirement adds an extra step to the initial user experience and may not be immediately discoverable for newcomers. The benefits of real-time monitoring are significant, and making this feature readily available would enhance the out-of-the-box experience with k6.

Describe the solution you'd like

The k6 web dashboard should be enabled by default when running k6 run. This would automatically start the web server and provide users with a link to the dashboard in the console output upon test execution.

To maintain flexibility and accommodate environments where a web server is not desired (e.g., certain CI/CD pipelines), a clear and simple opt-out mechanism should be provided. A suggested environment variable for this is K6_NO_WEB_DASHBOARD=true.

The existing K6_WEB_DASHBOARD_OPEN=true could still be used to automatically open the dashboard in the browser, but the default behavior would be to simply start the server and display the URL.

Describe alternatives you've considered

The current method of using K6_WEB_DASHBOARD=true is a viable alternative but is not as user-friendly as having the feature enabled by default. Another alternative would be to prompt the user to enable the dashboard on the first run, but this could add unnecessary complexity to the command-line interface.

Additional context

Enabling the web dashboard by default would align with a more "batteries-included" approach, offering a richer initial experience. Many developers and testers, especially those new to k6, would benefit from seeing their test results visualized without having to consult the documentation to enable this feature. The console output could look something like this:

          /\      |‾‾| /‾‾/   /‾‾/
     /\  /  \     |  |/  /   /  /
    /  \/    \    |     (   /   ‾‾\
   /          \   |  |\  \ |  (‾)  |
  / __________ \  |__| \__\ \_____/ .io

  execution: local
     script: test.js
     output: web dashboard available at http://localhost:5665

  scenarios: (100.00%) 1 scenario, 1 max VUs, 10s max duration (executing)
           * default: 1 looping VUs for 10s (gracefulStop: 30s)

running (00m01s/10s), 1/1 VUs, 1 complete and 0 interrupted iterations
...

This change would make a powerful k6 feature more accessible and improve the overall developer experience. ✨

[szkiba]

Here is an update on the implementation effort. A core issue has been identified that needs to be addressed in the xk6-dashboard extension first.

Problem:
When k6 tests are executed in parallel, each instance attempts to launch the dashboard on the default TCP port (5665). This is successful for the first instance, but subsequent instances fail with a "port in use" error, which incorrectly terminates the test run.

Proposed Solution:
The xk6-dashboard should be enhanced to manage this scenario. If the default port (5665) is already in use, the extension should log this as an informational error but not treat it as a fatal exception. In this state, the k6 test should proceed normally, behaving as if the dashboard were disabled.

Precedent for this Behavior:
This proposed logic is not new to k6. It is consistent with how the k6 REST API server, which is also enabled by default, already handles port conflicts. When the API server's default port is unavailable, k6 logs a warning and allows the test to proceed without the API functionality. Applying this same established pattern to the xk6-dashboard would create consistent and predictable behavior across k6 features.

Required Next Steps:

1. Implement the error-handling logic in the xk6-dashboard repository.
2. Publish a new release of xk6-dashboard.
3. Integrate the new version into the k6 codebase.

This path will resolve the underlying conflict and unblock the final implementation of this feature.

[szkiba]

⚠️ Heads-up: Potential Dependency Conflict

I've identified a potential dependency conflict that will affect the integration of the new xk6-dashboard release.

The Issue

The xk6-dashboard repository contains a separate CLI tool (k6-web-dashboard). A build-time utility used to automatically generate its documentation has a dependency on spf13/cobra version 1.9.1. The main k6 repository, however, currently uses the older spf13/cobra version 1.4.0.

This mismatch presents two potential paths forward for integration:

1. Keep cobra at v1.4.0 in k6. In this scenario, we would need to disable the automatic documentation generation for the k6-web-dashboard CLI tool to avoid the conflict.
2. Upgrade cobra in k6. This would involve updating the spf13/cobra library in the main k6 project to v1.9.1 or a newer version, resolving the conflict directly.

---

To the @grafana/k6 , what is your opinion on updating the spf13/cobra version? Upgrading seems like a cleaner long-term solution, but I'd appreciate your input.