Skip to content

Update UnitTestBot Go docs #2283

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.

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

Merged
merged 2 commits into from
Jul 28, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
17 changes: 10 additions & 7 deletions docs/GoSupport.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ UnitTestBot Go automatically generates ready-to-use unit tests for Go programs.
With UnitTestBot Go, you can find bugs in your code and fixate the desired program behavior with less effort.

The project is under development,
so feel free to [contribute](https://github.com/UnitTestBot/UTBotJava/blob/main/utbot-go/docs/DEVELOPERS_GUIDE.md).
so feel free to [contribute](https://github.com/UnitTestBot/UTBotJava/blob/main/utbot-go/docs/DEVELOPER_GUIDE.md).

## Features and details

Expand All @@ -15,14 +15,14 @@ inserts these values into the user functions, and executes the resulting test ca

### Supported types for function parameters

Now UnitTestBot Go can generate values for _primitive types_, _arrays_, _slices_ and _structs_.
Now UnitTestBot Go can generate values for _primitive types_, _arrays_, _slices_, _maps_, _structs_, _channels_, _interfaces_, and _pointers_.

For _floating point types_, UnitTestBot Go supports working with _infinity_ and _NaN_.

### Supported types for the returned results

For the returned function results,
UnitTestBot Go supports the `error` type as well as all the types supported for the function parameters.
UnitTestBot Go supports the `error` type as well as all the types supported for the function parameters except _interfaces_ and _channels_.

It also captures `panic` cases correctly.

Expand Down Expand Up @@ -85,7 +85,7 @@ Please refer to [UnitTestBot user guide](https://github.com/UnitTestBot/UTBotJav

### Requirements

* Java SDK 11 or later
* Java SDK 17 or later
* Go SDK 1.18 or later
* Properly configured `go.mod` file for the code under test
* GCC and `github.com/stretchr/testify/assert` installed
Expand Down Expand Up @@ -113,15 +113,18 @@ java -jar utbot-cli-2022.8-beta.jar runGo --help
`generateGo` options:

* `-s, --source TEXT`, _required_: specifies a Go source file to generate tests for.
* `-f, --function TEXT`, _required_: specifies a function name to generate tests for. Can be used multiple times to select multiple
functions.
* `-go, --go-path TEXT`, _required_: specifies a path to a Go executable. For example, `/usr/local/go/bin/go`.
* `-f, --function TEXT`: specifies a function name to generate tests for. Can be used multiple times to select multiple functions.
* `-m, --method TEXT`: specifies a method name to generate tests for. Can be used multiple times to select multiple methods.
* `-go TEXT`, _required_: specifies a path to a Go executable. For example, `/usr/local/go/bin/go`.
* `-gopath TEXT`, _required_: specifies a path to your workspace location. It defaults to a directory named `go` in your home directory: `$HOME/go` for Unix, `$home/go` for Plan 9, and `%USERPROFILE%\go` (usually `C:\Users\YourName\go`) for Windows.
* `-parallel INT`: specifies the number of fuzzing processes running at once (eight by default).
* `-et, --each-execution-timeout INT`: specifies a timeout in milliseconds for each target function execution.
The default timeout is 1,000 ms.
* `-at, --all-execution-timeout INT`: specifies a timeout in milliseconds for all target function executions.
The default timeout is 60,000 ms.
* `-p, --print-test`: specifies whether a test should be printed out to `StdOut`. Disabled by default.
* `-w, --overwrite`: specifies whether to overwrite the output test file if it already exists. Disabled by default.
* `-fm, --fuzzing-mode`: stops test generation when a `panic` situation, an error, or timeout occurs (only one test will be generated for one of these cases).
* `-h, --help`: shows a help message and exits.

`runGo` options:
Expand Down
30 changes: 17 additions & 13 deletions utbot-go/docs/DEVELOPER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,41 +9,45 @@ flowchart TB
A["Target selection and configuration (IntelliJ IDEA plugin or CLI)"]:::someclass --> B(Go source code analysis)
classDef someclass fill:#b810

B --> C(Fuzzing)
C --> D(Executing functions)
D --> E(Getting results)
E --> C
C ---> F(Test file generation)
B --> C(Code instrumentation)
C --> D(Generation of arguments)
D --> E(Executing functions)
E --> F(Getting results)
F --> D
D ---> G(Test file generation)
```

### Target selection and configuration

A user manually selects the target source file and functions to generate the tests for.
Test generation settings are also configured manually.

### Code instrumentation

After each line in a function, UnitTestBot Go adds logging about this line traversal during the execution.

### Go source code analysis

UnitTestBot Go collects information about the target functions:
* signatures and type information (in the basic version);
* constants in the function bodies (to be implemented).
UnitTestBot Go gains information about the `int` or `uint` value size in bits, and information about the target functions:
* signatures and type information;
* constants in the function bodies.

As a result, UnitTestBot Go gets an internal
representation of the target functions.

### Fuzzing
### Generation of arguments

During the fuzzing stage, UnitTestBot Go generates the input values for the source code.
At this stage, UnitTestBot Go generates the input values for the target functions.

### Executing target functions

UnitTestBot Go executes the target functions with the generated values as arguments and analyses the result
to continue or stop the generation process.
UnitTestBot Go executes the target functions with the generated values as arguments.

### Getting results

The result of target function execution is sent to the fuzzer for analysis:
coverage rate information guides the following value generation process.
Based on this feedback,
Based on remaining time,
the fuzzer decides whether it should continue or stop generating input values.

### Test code generation
Expand Down