Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/apitoolkit/doctests
Doctests: Test interactive Golang examples in your code comments
https://github.com/apitoolkit/doctests
Last synced: about 17 hours ago
JSON representation
Doctests: Test interactive Golang examples in your code comments
- Host: GitHub
- URL: https://github.com/apitoolkit/doctests
- Owner: apitoolkit
- Created: 2022-06-21T10:13:15.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-07-08T11:02:13.000Z (4 months ago)
- Last Synced: 2024-07-08T13:45:51.956Z (4 months ago)
- Language: Go
- Homepage:
- Size: 42 KB
- Stars: 5
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
Awesome Lists containing this project
README
# Doctests: Test interactive Golang examples in your code comments
`doctest` is a tool that checks code examples and properties in Go comments.
It is similar in spirit to the [popular Python module with the same name](https://docs.python.org/3/library/doctest.html) and [Haskell library with same name](https://github.com/sol/doctest).
## Getting Started
https://github.com/apitoolkit/doctests/assets/6564482/e94dbbbf-224f-4c52-9ad6-36cc3767e645
### Installation
You can install Doctests via go modules via:
```go
go install github.com/apitoolkit/doctests@latest
```
### Setup Doctests in nvim/vim via lspconfig
Doctest includes an lsp client, which is installed via the command above.
But to use it in your nvim editor, simply add the following code to your nvim lua config, to instruct your editor on how to use it. Note that this depends on the [lspconfig lua plugin](https://github.com/neovim/nvim-lspconfig).
```lua
local lspconfig = require 'lspconfig'
local configs = require 'lspconfig.configs'
local util = require 'lspconfig.util'
-- Check if the config is already defined (useful when reloading this file)
if not configs.doctests then
configs.doctests = {
default_config = {
cmd = {'doctests', 'lsp'};
settings = {};
filetypes = { 'go', 'gomod', 'gotmpl' },
root_dir = function(fname)
return util.root_pattern 'go.work'(fname) or util.root_pattern('go.mod', '.git')(fname)
end,
single_file_support = true,
};
}
end
lspconfig.doctests.setup{}
```
### Running Doctest from CI or command line
The easiest way to run a doctest is via the CLI. To execute Doctest in the current Directory, simply run the doctest command with no arguments in the given directory.
```go
doctests
```
Or give it a path or list of file paths or filepath glob
```go
doctests ./main.go
```
OR
```go
doctests ./main.go ./abc.go
```
OR (For every file in a project tree)
```go
doctests ./**/*.go
```
### Wrting Doctests
`Doctest` comment lines always start with `// >>>`. The 3 greater than signs allows Doctest to detect that those lines are to be executed. The result is always inserted into the next line.
```go
package adder
// Add adds two numbers
// >>> adder.Add(1, 2)
// 3
func Add(a int, b int) int {
return a+b
}
```
Notice that it's important to include the package name when calling functions.
## Contributors
- Anthony Alaribe
- Arne Wielding
- Mohamed Nabil
- Omar Ahmed