Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: add docs/checkhealth around gotestsum, add docs on -race and cgo #211

Merged
merged 5 commits into from
Nov 3, 2024
Merged

chore: add docs/checkhealth around gotestsum, add docs on -race and cgo #211

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4735e91
docs: collapse install examples
fredrikaverpil Nov 3, 2024
843a2ec
docs: mention -race and cgo
fredrikaverpil Nov 3, 2024
f164ca9
feat(health): provide more info around gotestsum and windows
fredrikaverpil Nov 3, 2024
8962907
docs: refine notes on gotestsum/windows
fredrikaverpil Nov 3, 2024
1068364
docs: improve requirement
fredrikaverpil Nov 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 40 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,10 @@ And here, a comparison in number of GitHub stars between the projects:

> [!NOTE]
>
> Requires Neovim 0.10.0.
> Requires Neovim 0.10.0 and above.

### 💤 Lazy.nvim
<details>
<summary>💤 Lazy.nvim</summary>

```lua
return {
Expand Down Expand Up @@ -92,7 +93,10 @@ return {
> See the [Lazy versioning spec](https://lazy.folke.io/spec/versioning) for more
> details.

### 🌒 Rocks.nvim
</details>

<details>
<summary>🌒 Rocks.nvim</summary>

The adapter is available via
[luarocks package](https://luarocks.org/modules/fredrikaverpil/neotest-golang):
Expand All @@ -113,7 +117,10 @@ consider setting up neotest and its adapters in a
> Please note that [leoluz/nvim-dap-go](https://github.com/leoluz/nvim-dap-go)
> (required for DAP) is not on luarocks as of writing this.

### ❄️ Nix & Home manager
</details>

<details>
<summary>❄️ Nix & Home manager</summary>

```nix
{
Expand Down Expand Up @@ -156,12 +163,14 @@ consider setting up neotest and its adapters in a
}
```

</details>

## ⚙️ Configuration

| 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`. Note: [`-tags` usage](https://github.com/fredrikaverpil/neotest-golang#using-build-tags), [pass args as function](https://github.com/fredrikaverpil/neotest-golang#pass-arguments-as-function-instead-of-table). |
| `go_test_args` | `{ "-v", "-race", "-count=1" }` | Arguments to pass into `go test`. Notes: [`-tags` usage](https://github.com/fredrikaverpil/neotest-golang#using-build-tags), [pass args as function](https://github.com/fredrikaverpil/neotest-golang#pass-arguments-as-function-instead-of-table). |
| `gotestsum_args` | `{ "--format=standard-verbose" }` | Arguments to pass into `gotestsum`. Notes: [`-tags` usage](https://github.com/fredrikaverpil/neotest-golang#using-build-tags), [pass args as function](https://github.com/fredrikaverpil/neotest-golang#pass-arguments-as-function-instead-of-table). Will only be used if `runner = "gotestsum"`. The `go_test_args` still applies. |
| `go_list_args` | `{}` | Arguments to pass into `go list`. Note: [`-tags` usage](https://github.com/fredrikaverpil/neotest-golang#using-build-tags), [pass args as function](https://github.com/fredrikaverpil/neotest-golang#pass-arguments-as-function-instead-of-table). |
| `dap_go_opts` | `{}` | Options to pass into `require("dap-go").setup()`. Note: [`-tags` usage](https://github.com/fredrikaverpil/neotest-golang#using-build-tags), [pass args as function](https://github.com/fredrikaverpil/neotest-golang#pass-arguments-as-function-instead-of-table). |
Expand All @@ -170,6 +179,17 @@ consider setting up neotest and its adapters in a
| `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. |

> [!NOTE]
>
> The `-race` flag (in `go_test_args`) requires CGO to be enabled and a C
> compiler (such as GCC) to be installed. I have included this as it provides
> good production defaults.

> [!IMPORTANT]
>
> The `gotestsum` runner is recommended for Windows users or if you are using
> Ubuntu snaps. You can read more below on `gotestsum`.

### Example configuration: custom `go test` arguments

```lua
Expand Down Expand Up @@ -260,9 +280,9 @@ return {

For a more verbose example, see the "extra everything" example config.

### Use `gotestsum` as test runner
### Using `gotestsum` as test runner

To improve reliability, you can choose to run tests using
To improve reliability, you can choose to set
[`gotestsum`](https://github.com/gotestyourself/gotestsum) as the test runner.
This tool allows you to use one format for stdout while simultaneously writing
test output to a JSON file. `gotestsum` actually calls `go test` behind the
Expand All @@ -271,10 +291,19 @@ Using `gotestsum` offers the following benefits:

- When you "attach" to a running test, you'll see clean `go test` output instead
of having to navigate through difficult-to-read JSON.
- On certain platforms or terminals, there's a risk of ANSI codes or other
characters being seemingly randomly inserted into the JSON test output. This
can corrupt the data and cause problems with JSON decoding. Enabling
`gotestsum` eliminates these issues.
- On certain platforms (such as Windows) or terminals, there's a risk of ANSI
codes or other characters being seemingly randomly inserted into the JSON test
output. This can corrupt the data and cause problems with test output JSON
decoding. Enabling `gotestsum` eliminates these issues, as the test output is
then written directly to file.

> [!INFO]
>
> See
> [this issue comment](https://github.com/fredrikaverpil/neotest-golang/issues/193#issuecomment-2362845806)
> for more details on reported issues on Windows and Ubuntu snaps.

#### Configure neotest-golang to use `gotestsum` as test runner

Make the `gotestsum` command availalbe via
[mason.nvim](https://github.com/williamboman/mason.nvim) or by running the
Expand Down
47 changes: 44 additions & 3 deletions lua/neotest-golang/health.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,11 @@ function M.check()
M.is_plugin_available("dap-go")

start("Gotestsum (optional)")
M.binary_found_on_path("gotestsum")
M.gotestsum_recommended_on_windows()
M.gotestsum_installed_but_not_used()
end

function M.binary_found_on_path(executable)
function M.binary_found_on_path(executable, supress_warn)
local found = vim.fn.executable(executable)
if found == 1 then
ok(
Expand All @@ -41,7 +42,11 @@ function M.binary_found_on_path(executable)
)
return true
else
warn("Binary '" .. executable .. "' not found on PATH")
if supress_warn then
ok("Binary '" .. executable .. "' not found on PATH")
else
warn("Binary '" .. executable .. "' not found on PATH")
end
end
return false
end
Expand Down Expand Up @@ -107,4 +112,40 @@ function M.treesitter_parser_installed(lang)
end
end

local function is_windows_uname()
local os_info = vim.loop.os_uname()
return os_info.sysname:lower():find("windows") ~= nil
end

function M.gotestsum_recommended_on_windows()
if is_windows_uname() then
if options.get().runner ~= "gotestsum" then
warn(
"On Windows, gotestsum runner is recommended for increased stability."
.. " See the README for linkts to issues/discussions and more info."
)
else
ok("On Windows and with gotestsum set up as runner.")
end
end
end

function M.gotestsum_installed_but_not_used()
local found = M.binary_found_on_path("gotestsum", true)

-- found but not active
if found and options.get().runner ~= "gotestsum" then
local msg = "Found gotestsum to be installed, but not set as test runner."
if is_windows_uname() then
warn(msg)
else
info(msg)
end

-- found and active
elseif found and options.get().runner == "gotestsum" then
ok("Tests will be executed by gotestsum.")
end
end

return M
Loading