From cbb159127253538e2ddbbd585352bcbd08e7ca02 Mon Sep 17 00:00:00 2001 From: Egipti Pavel Date: Tue, 13 Jun 2023 14:01:35 +0300 Subject: [PATCH 1/2] Update Go docs --- docs/GoSupport.md | 17 ++++++++++------- utbot-go/docs/DEVELOPER_GUIDE.md | 31 ++++++++++++++++++------------- 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/docs/GoSupport.md b/docs/GoSupport.md index 04c06ea00a..88b6b1c86c 100644 --- a/docs/GoSupport.md +++ b/docs/GoSupport.md @@ -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 @@ -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. @@ -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 @@ -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 the location of your workspace. It defaults to a directory named `go` inside your home directory, so `$HOME/go` on Unix, `$home/go` on Plan 9, and `%USERPROFILE%\go` (usually `C:\Users\YourName\go`) on Windows. +* `-parallel INT`: specifies the number of fuzzing processes running at once, default 8. * `-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, 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: diff --git a/utbot-go/docs/DEVELOPER_GUIDE.md b/utbot-go/docs/DEVELOPER_GUIDE.md index 3aaa19c1d6..55f8d78900 100644 --- a/utbot-go/docs/DEVELOPER_GUIDE.md +++ b/utbot-go/docs/DEVELOPER_GUIDE.md @@ -9,11 +9,12 @@ 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 @@ -21,29 +22,33 @@ flowchart TB A user manually selects the target source file and functions to generate the tests for. Test generation settings are also configured manually. +### Code instrumentation + +UnitTestBot Go adds logging about the passage of a given line during the execution +after each line in functions. + ### 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 collects the size in bits of an int or uint value 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 From 0526d8e61f565ff0f293a16fd4896012c48c0995 Mon Sep 17 00:00:00 2001 From: Pavel Egipti Date: Fri, 28 Jul 2023 16:12:06 +0300 Subject: [PATCH 2/2] Fix remarks --- docs/GoSupport.md | 8 ++++---- utbot-go/docs/DEVELOPER_GUIDE.md | 5 ++--- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/GoSupport.md b/docs/GoSupport.md index 88b6b1c86c..10518a49a0 100644 --- a/docs/GoSupport.md +++ b/docs/GoSupport.md @@ -15,7 +15,7 @@ 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_, _maps_, _structs_, _channels_, _interfaces_ and _pointers_. +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_. @@ -116,15 +116,15 @@ java -jar utbot-cli-2022.8-beta.jar runGo --help * `-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 the location of your workspace. It defaults to a directory named `go` inside your home directory, so `$HOME/go` on Unix, `$home/go` on Plan 9, and `%USERPROFILE%\go` (usually `C:\Users\YourName\go`) on Windows. -* `-parallel INT`: specifies the number of fuzzing processes running at once, default 8. +* `-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, error or timeout occurs (only one test will be generated for one of these cases). +* `-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: diff --git a/utbot-go/docs/DEVELOPER_GUIDE.md b/utbot-go/docs/DEVELOPER_GUIDE.md index 55f8d78900..86aea31c0d 100644 --- a/utbot-go/docs/DEVELOPER_GUIDE.md +++ b/utbot-go/docs/DEVELOPER_GUIDE.md @@ -24,12 +24,11 @@ Test generation settings are also configured manually. ### Code instrumentation -UnitTestBot Go adds logging about the passage of a given line during the execution -after each line in functions. +After each line in a function, UnitTestBot Go adds logging about this line traversal during the execution. ### Go source code analysis -UnitTestBot Go collects the size in bits of an int or uint value and information about the target functions: +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.