feat: gotestsum

README.md

@@ -75,13 +75,15 @@ You can run `:checkhealth neotest-golang` to review common issues.
 
 ## ⚙️ Configuration
 
-| Argument                 | Default value                   | Description                                                                                                                                                          |
-| ------------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `go_test_args`           | `{ "-v", "-race", "-count=1" }` | Arguments to pass into `go test`.                                                                                                                                    |
-| `dap_go_opts`            | `{}`                            | Options to pass into `require("dap-go").setup()`.                                                                                                                    |
-| `testify_enabled`        | `false`                         | Enable support for [testify](https://github.com/stretchr/testify) suites. See [here](https://github.com/fredrikaverpil/neotest-golang#testify-suites) for more info. |
-| `warn_test_name_dupes`   | `true`                          | Warn about duplicate test names within the same Go package.                                                                                                          |
-| `warn_test_not_executed` | `true`                          | Warn if test was not executed.                                                                                                                                       |
+| Argument                 | Default value                     | Description                                                                                                                                                          |
+| ------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runner`                 | `go`                              | Defines the test runner. Valid values: `go` or `gotestsum`.                                                                                                          |
+| `go_test_args`           | `{ "-v", "-race", "-count=1" }`   | Arguments to pass into `go test`.                                                                                                                                    |
+| `gotestsum_args`         | `{ "--format=standard-verbose" }` | Arguments to pass into `gotestsum`. Will only be used if `runner = "gotestsum"`.                                                                                     |
+| `dap_go_opts`            | `{}`                              | Options to pass into `require("dap-go").setup()`.                                                                                                                    |
+| `testify_enabled`        | `false`                           | Enable support for [testify](https://github.com/stretchr/testify) suites. See [here](https://github.com/fredrikaverpil/neotest-golang#testify-suites) for more info. |
+| `warn_test_name_dupes`   | `true`                            | Warn about duplicate test names within the same Go package.                                                                                                          |
+| `warn_test_not_executed` | `true`                            | Warn if test was not executed.                                                                                                                                       |
 
 ### Example configuration: custom `go test` arguments
 
@@ -170,6 +172,43 @@ return {
 }
 ```
 
+### Use `gotestsum` as test runner
+
+For increased robustness, you can opt in to run tests with
+[`gotestsum`](https://github.com/gotestyourself/gotestsum) as test runner. It
+brings the capability of using one format for stdout/sterr and at the same time
+write the test output to JSON file. Technically, it will call `go test` under
+the hood, and therefore the `go_test_args` configuration is still valid and will
+apply.
+
+Using `gotestsum` will bring the following:
+
+- When attaching to a running test, you will now be able to view clean `go test`
+  output instead of wading through hard-to-read JSON.
+- On some platforms/terminals, there's a risk of having characters such as ANSI
+  codes injected seemingly randomly into the JSON test output, garbling it up
+  and resulting in issues with JSON decoding. In such cases, enable `gotestsum`
+  to rid such issues.
+
+First install it:
+
+```bash
+go install gotest.tools/gotestsum@latest
+```
+
+Then add the required configuration:
+
+```lua
+local config = { -- Specify configuration
+  runner = "gotestsum"
+}
+require("neotest").setup({
+  adapters = {
+    require("neotest-golang")(config), -- Apply configuration
+  },
+})
+```
+
 ### Example configuration: extra everything
 
 <details>