From 2ee709ddc06fb449b69a4c7744b5d343f61dc161 Mon Sep 17 00:00:00 2001 From: Olga Naumenko <64418523+olganaumenko@users.noreply.github.com> Date: Mon, 20 Mar 2023 17:05:26 +0300 Subject: [PATCH 1/4] Python, JavaScript, Go docs updated --- docs/JavaScriptSupport.md | 48 ++++++++++++++++++---------------- utbot-go/README.md | 33 +++++++++++------------ utbot-python/README.md | 55 ++++++++++++++------------------------- 3 files changed, 63 insertions(+), 73 deletions(-) diff --git a/docs/JavaScriptSupport.md b/docs/JavaScriptSupport.md index ecd7d39b09..42608f9b3b 100644 --- a/docs/JavaScriptSupport.md +++ b/docs/JavaScriptSupport.md @@ -1,38 +1,42 @@ -# UnitTestBot JavaScript plugin setup +# UnitTestBot JavaScript -## How to start using UnitTestBot JavaScript +[UnitTestBot](https://www.utbot.org/) is the tool for automated unit test generation available as an IntelliJ IDEA plugin, or a command-line interface. -1. [Install](https://www.jetbrains.com/idea/download/) the latest version of IntelliJ IDEA Ultimate. -2. [Install](https://plugins.jetbrains.com/plugin/19445-unittestbot) the latest version of UnitTestBot plugin. -3. [Install](https://nodejs.org/en/download/) Node.js 10.0.0 or later. Add Node.js to environment variables for better experience. -4. In your IntelliJ IDEA, go to **File** > **Settings** > **Tools** > **UnitTestBot** and enable **Experimental languages support**. -5. Go to **File** > **Settings** > **Languages & Frameworks**, choose **Node.js** and check if the path to Node.js executable file is specified. -6. In a JavaScript file, press **Alt+Shift+U** to open the generation dialog. +Now UnitTestBot provides fuzzing-based support for JavaScript. -## Troubleshooting: _npm_ cannot install requirements +## IntelliJ IDEA plugin -1. The system prohibits installation +### Requirements -Solution: run _cmd_ via `sudo` or with administrator access, run `npm install -g `. +1. The [latest version of IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/download/) +2. The [latest version of UnitTestBot plugin](https://plugins.jetbrains.com/plugin/19445-unittestbot) +3. [Node.js 10.0.0 or later](https://nodejs.org/en/download/) (we recommend that you add Node.js to environment variables) + +_Note:_ when _npm_ cannot install requirements, try troubleshooting. +1. If the system prohibits installation: run _cmd_ via `sudo` or with administrator access, run `npm install -g `. +2. If Node.js is missing, or _npm_ is not installed: install Node.js with default configuration from the official website. -2. Node.js is missing, or _npm_ is not installed +### How to use -Solution: install Node.js with default configuration from the official website. +1. In your IntelliJ IDEA, go to **File** > **Settings** > **Tools**, choose **UnitTestBot** and enable **Experimental languages support**. + + **(!) NOTE:** be sure to enable this option for **_each_** project. -# JavaScript Command Line Interface usage +2. Go to **File** > **Settings** > **Languages & Frameworks**, choose **Node.js** and check if the path to Node.js executable file is specified. +3. In a JavaScript file, press **Alt+Shift+U** to open the generation dialog. -## Build +## Command-line interface (CLI) -JAR file can be built in [GitHub Actions](https://github.com/UnitTestBot/UTBotJava/actions/workflows/publish-plugin-and-cli-from-branch.yml) with the `publish-plugin-and-cli-from-branch` script. +### Build -## Requirements +JAR file can be built in [GitHub Actions](https://github.com/UnitTestBot/UTBotJava/actions/workflows/publish-plugin-and-cli-from-branch.yml) with the `publish-plugin-and-cli-from-branch` script. -* [Install](https://nodejs.org/en/download/) Node.js 10.0.0 or later -* [Install](https://www.oracle.com/java/technologies/downloads/) Java 11 or later -* Install _nyc_ 15.1.0 or later: `> npm install -g nyc` -* Install Mocha 10.0.0 or later: `> npm install -g mocha` +### Requirements -## Basic usage +* [Node.js 10.0.0 or later](https://nodejs.org/en/download/) +* [Java 11 or later](https://www.oracle.com/java/technologies/downloads/) +* _nyc_ 15.1.0 or later: `> npm install -g nyc` +* Mocha 10.0.0 or later: `> npm install -g mocha` ### Generate tests: `generate_js` diff --git a/utbot-go/README.md b/utbot-go/README.md index 4ce416e740..fc1c72a9a7 100644 --- a/utbot-go/README.md +++ b/utbot-go/README.md @@ -10,19 +10,19 @@ so feel free to [contribute](https://github.com/UnitTestBot/UTBotJava/blob/main/ ## Features and details UnitTestBot Go now implements the _basic fuzzing technique_. -It generates input values with respect to parameter types, +It generates input values considering the parameter types, inserts these values into the user functions, and executes the resulting test cases. ### Supported types for function parameters -At the moment, UnitTestBot Go is able to generate values for _primitive types_, _arrays_, _slices_ and _structs_. +Now UnitTestBot Go can generate values for _primitive types_, _arrays_, _slices_ and _structs_. 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 in addition to 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. It also captures `panic` cases correctly. @@ -58,11 +58,9 @@ use the `go mod tidy` command. For editing and formatting `go.mod` files, use th In the future, we plan to make UnitTestBot Go working with arbitrary code as input and generate the simplest Go projects automatically. -## Installation and usage +## IntelliJ IDEA plugin -### IntelliJ IDEA plugin - -#### Requirements +### Requirements * IntelliJ IDEA (Ultimate Edition) — versions from 2022.2 to 2022.2.4 * Go SDK 1.18 or later @@ -70,32 +68,35 @@ Go projects automatically. * Properly configured `go.mod` file for the code under test * `github.com/stretchr/testify/assert` Go module installed (IntelliJ IDEA automatically offers to install it as soon as the tests are generated) -#### Installation +### Installation + +Please refer to [UnitTestBot user guide](https://github.com/UnitTestBot/UTBotJava/wiki/Install-or-update-plugin). + +### Usage -To install the UnitTestBot Go plugin in IntelliJ IDEA, refer to [UnitTestBot user guide](https://github.com/UnitTestBot/UTBotJava/wiki/Install-or-update-plugin). +1. In your IntelliJ IDEA, go to **File** > **Settings** > **Tools**, choose **UnitTestBot** and enable **Experimental languages support**. -#### Usage + **(!) NOTE:** be sure to enable this option for **_each_** project. -1. In your IntelliJ IDEA, go to **File** > **Settings** > **Tools** > **UnitTestBot** and enable **Experimental languages support**. 2. Open a `.go` file and press **Alt+Shift+U**. 3. In the **Generate Tests with UnitTestBot** window, you can configure the settings. -### CLI +## Command-line interface (CLI) -#### Requirements +### Requirements * Java SDK 11 or later * Go SDK 1.18 or later * Properly configured `go.mod` file for the code under test * GCC as well as `github.com/stretchr/testify/assert` and `golang.org/x/tools@v0.4.0` Go modules installed -#### Installation +### Installation To install the UnitTestBot Go CLI application, go to GitHub, scroll through the release notes and click **Assets**. Download the zip-archive named like **utbot-cli-VERSION**. Extract the JAR file from the archive. -#### Usage +### Usage Run the extracted JAR file using a command line: `generateGo` and `runGo` actions are supported for now. To find info about the options for these actions, @@ -138,4 +139,4 @@ java -jar utbot-cli-2022.8-beta.jar runGo --help ## Contributing to UnitTestBot Go To take part in project development or learn more about UnitTestBot Go, check -out the [Developer guide](docs/DEVELOPER_GUIDE.md) and our [future plans](docs/FUTURE_PLANS.md). \ No newline at end of file +out the [Developer guide](docs/DEVELOPER_GUIDE.md) and our [plans](docs/FUTURE_PLANS.md). \ No newline at end of file diff --git a/utbot-python/README.md b/utbot-python/README.md index e5c0f6529b..b4a622e90f 100644 --- a/utbot-python/README.md +++ b/utbot-python/README.md @@ -1,48 +1,33 @@ -# UTBot for Python +# UnitTestBot Python -UTBot is the tool for automated unit test generation. You can read more about this project [on the official website](https://www.utbot.org/). +[UnitTestBot](https://www.utbot.org/) is the tool for automated unit test generation available as an IntelliJ IDEA plugin, or a command-line interface. -This is the support of UTBot for Python. +Now UnitTestBot provides fuzzing-based support for Python. -UTBot tries to maximize the code coverage while minimizing the number of tests. For now, we use only the fuzzing technique for Python. +## Requirements -# Get started +1. Python 3.8 or 3.9 (UnitTestBot Python has been tested to provide support for these versions; some Python 3.10 syntax is not supported) +2. [Python plugin](https://plugins.jetbrains.com/plugin/631-python) for IntelliJ IDEA +3. IntelliJ IDEA 2022.1 -There are two ways to use UTBot: as an IntelliJ IDEA plugin or through a command line interface. +If you already have a Python project, you usually have no need to install or configure anything else, but if you have trouble with launching UnitTestBot Python, please refer to [advanced requirements section](docs/CLI.md#requirements). -You can download both archives [here](https://github.com/UnitTestBot/UTBotJava/actions/runs/2956160534). +_Note:_ the `com.intellij.modules.python` package should be specified in `/utbot-intellij/resources/plugin.xml` as a dependency for using Python PSI tree. -## Python requirements +## How to install and use -UTBot Python has been tested on Python 3.8 and 3.9. Some syntax from Python 3.10 is not supported. +To try UnitTestBot Python as an _**IntelliJ IDEA plugin**_: +1. Download the corresponding [archive](https://github.com/UnitTestBot/UTBotJava/actions/runs/2956160534). +2. [Install](https://www.jetbrains.com/help/idea/managing-plugins.html#install_plugin_from_disk) the plugin from the downloaded archive. +3. Configure the Python interpreter for your project and make sure IntelliJ IDEA resolves all the imports. +4. In your IntelliJ IDEA, go to **File** > **Settings** > **Tools**, choose **UnitTestBot** and enable **Experimental languages support**. -Usually nothing has to be done manually, but if you have any troubles with requirements, refer to [requirements section](docs/CLI.md#requirements) in CLI documentation. + **(!) NOTE:** be sure to enable this option for **_each_** project. -## IntelliJ IDEA plugin +5. To generate tests, place the caret at the required function and press **Alt+Shift+U** (**Alt+U, Alt+T** in Ubuntu). -IntelliJ IDEA version should be 2022.1. +To use UnitTestBot Python via _**command-line interface**_, please refer to the [CLI guide](docs/CLI.md). -1. Make sure you already have the Python plugin installed. +## How to contribute and get support -2. Download the archive with the plugin and install it following [this instruction](https://www.jetbrains.com/help/idea/managing-plugins.html#install_plugin_from_disk). - -3. Configure the Python interpreter for your project and make sure that IDEA resolves all imports. - -4. After indexing has finished, move the cursor to a function, press ALT+SHIFT+U (or ALT+U, ALT+T in Ubuntu), and generate tests. - -### Dependency - -Package `com.intellij.modules.python` in `/utbot-intellij/resources/plugin.xml` is necessary dependecy for now, it is needed to use Python Psi tree. - - -## Command line interface - -You can find documentation on CLI usage [here](docs/CLI.md). - -# Contribute - -Read more in [UTBot Java Readme](../README.md#contribute-to-utbot-java). - -# Support - -Read more in [UTBot Java Readme](../README.md#find-support). +To get information on contributing and getting support, please see [UnitTestBot Java Readme](https://github.com/UnitTestBot/UTBotJava#readme). From f4f8b45aab23bfebed41da66dcde45330b516b43 Mon Sep 17 00:00:00 2001 From: Olga Naumenko <64418523+olganaumenko@users.noreply.github.com> Date: Wed, 22 Mar 2023 11:34:24 +0300 Subject: [PATCH 2/4] Py and Go doss moved to docs folder and updated --- utbot-go/README.md => docs/GoSupport.md | 4 ++-- docs/JavaScriptSupport.md | 2 +- utbot-python/README.md => docs/PythonSupport.md | 17 ++++++++--------- 3 files changed, 11 insertions(+), 12 deletions(-) rename utbot-go/README.md => docs/GoSupport.md (96%) rename utbot-python/README.md => docs/PythonSupport.md (59%) diff --git a/utbot-go/README.md b/docs/GoSupport.md similarity index 96% rename from utbot-go/README.md rename to docs/GoSupport.md index fc1c72a9a7..066c87c2db 100644 --- a/utbot-go/README.md +++ b/docs/GoSupport.md @@ -88,7 +88,7 @@ Please refer to [UnitTestBot user guide](https://github.com/UnitTestBot/UTBotJav * Java SDK 11 or later * Go SDK 1.18 or later * Properly configured `go.mod` file for the code under test -* GCC as well as `github.com/stretchr/testify/assert` and `golang.org/x/tools@v0.4.0` Go modules installed +* GCC and `github.com/stretchr/testify/assert` installed ### Installation @@ -139,4 +139,4 @@ java -jar utbot-cli-2022.8-beta.jar runGo --help ## Contributing to UnitTestBot Go To take part in project development or learn more about UnitTestBot Go, check -out the [Developer guide](docs/DEVELOPER_GUIDE.md) and our [plans](docs/FUTURE_PLANS.md). \ No newline at end of file +out the [Developer guide](../utbot-go/docs/DEVELOPER_GUIDE.md) and our [plans](../utbot-go/docs/FUTURE_PLANS.md). \ No newline at end of file diff --git a/docs/JavaScriptSupport.md b/docs/JavaScriptSupport.md index 42608f9b3b..650d385ac0 100644 --- a/docs/JavaScriptSupport.md +++ b/docs/JavaScriptSupport.md @@ -9,7 +9,7 @@ Now UnitTestBot provides fuzzing-based support for JavaScript. ### Requirements 1. The [latest version of IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/download/) -2. The [latest version of UnitTestBot plugin](https://plugins.jetbrains.com/plugin/19445-unittestbot) +2. UnitTestBot plugin: please refer to [UnitTestBot user guide](https://github.com/UnitTestBot/UTBotJava/wiki/Install-or-update-plugin). 3. [Node.js 10.0.0 or later](https://nodejs.org/en/download/) (we recommend that you add Node.js to environment variables) _Note:_ when _npm_ cannot install requirements, try troubleshooting. diff --git a/utbot-python/README.md b/docs/PythonSupport.md similarity index 59% rename from utbot-python/README.md rename to docs/PythonSupport.md index b4a622e90f..e27ccf7170 100644 --- a/utbot-python/README.md +++ b/docs/PythonSupport.md @@ -6,27 +6,26 @@ Now UnitTestBot provides fuzzing-based support for Python. ## Requirements -1. Python 3.8 or 3.9 (UnitTestBot Python has been tested to provide support for these versions; some Python 3.10 syntax is not supported) +1. Python 3.8 or later 2. [Python plugin](https://plugins.jetbrains.com/plugin/631-python) for IntelliJ IDEA 3. IntelliJ IDEA 2022.1 -If you already have a Python project, you usually have no need to install or configure anything else, but if you have trouble with launching UnitTestBot Python, please refer to [advanced requirements section](docs/CLI.md#requirements). +If you already have a Python project, you usually have no need to install or configure anything else, but if you have trouble with launching UnitTestBot Python, please refer to [advanced requirements section](../utbot-python/docs/CLI.md#requirements). _Note:_ the `com.intellij.modules.python` package should be specified in `/utbot-intellij/resources/plugin.xml` as a dependency for using Python PSI tree. ## How to install and use -To try UnitTestBot Python as an _**IntelliJ IDEA plugin**_: -1. Download the corresponding [archive](https://github.com/UnitTestBot/UTBotJava/actions/runs/2956160534). -2. [Install](https://www.jetbrains.com/help/idea/managing-plugins.html#install_plugin_from_disk) the plugin from the downloaded archive. -3. Configure the Python interpreter for your project and make sure IntelliJ IDEA resolves all the imports. -4. In your IntelliJ IDEA, go to **File** > **Settings** > **Tools**, choose **UnitTestBot** and enable **Experimental languages support**. +To try UnitTestBot Python in your IntelliJ IDEA: +1. To install the plugin, please refer to [UnitTestBot user guide](https://github.com/UnitTestBot/UTBotJava/wiki/Install-or-update-plugin). +2. Configure the Python interpreter for your project and make sure IntelliJ IDEA resolves all the imports. +3. In your IntelliJ IDEA, go to **File** > **Settings** > **Tools**, choose **UnitTestBot** and enable **Experimental languages support**. **(!) NOTE:** be sure to enable this option for **_each_** project. -5. To generate tests, place the caret at the required function and press **Alt+Shift+U** (**Alt+U, Alt+T** in Ubuntu). +4. To generate tests, place the caret at the required function and press **Alt+Shift+U** (**Alt+U, Alt+T** in Ubuntu). -To use UnitTestBot Python via _**command-line interface**_, please refer to the [CLI guide](docs/CLI.md). +To use UnitTestBot Python via command-line interface, please refer to the [CLI guide](../utbot-python/docs/CLI.md). ## How to contribute and get support From 78ae0d669c4ce1e88ce5060252674d686313529d Mon Sep 17 00:00:00 2001 From: Olga Naumenko <64418523+olganaumenko@users.noreply.github.com> Date: Fri, 24 Mar 2023 12:08:47 +0300 Subject: [PATCH 3/4] Updated Intellij IDEA version --- docs/GoSupport.md | 2 +- docs/JavaScriptSupport.md | 2 +- docs/PythonSupport.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/GoSupport.md b/docs/GoSupport.md index 066c87c2db..179e1b2c45 100644 --- a/docs/GoSupport.md +++ b/docs/GoSupport.md @@ -62,7 +62,7 @@ Go projects automatically. ### Requirements -* IntelliJ IDEA (Ultimate Edition) — versions from 2022.2 to 2022.2.4 +* IntelliJ IDEA Ultimate 2022.2 or later * Go SDK 1.18 or later * Compatible [Go plugin](https://plugins.jetbrains.com/plugin/9568-go) for IntelliJ IDEA * Properly configured `go.mod` file for the code under test diff --git a/docs/JavaScriptSupport.md b/docs/JavaScriptSupport.md index 650d385ac0..48c4412d28 100644 --- a/docs/JavaScriptSupport.md +++ b/docs/JavaScriptSupport.md @@ -8,7 +8,7 @@ Now UnitTestBot provides fuzzing-based support for JavaScript. ### Requirements -1. The [latest version of IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/download/) +1. IntelliJ IDEA Ultimate 2022.2 or later 2. UnitTestBot plugin: please refer to [UnitTestBot user guide](https://github.com/UnitTestBot/UTBotJava/wiki/Install-or-update-plugin). 3. [Node.js 10.0.0 or later](https://nodejs.org/en/download/) (we recommend that you add Node.js to environment variables) diff --git a/docs/PythonSupport.md b/docs/PythonSupport.md index e27ccf7170..dcaa35236e 100644 --- a/docs/PythonSupport.md +++ b/docs/PythonSupport.md @@ -6,9 +6,9 @@ Now UnitTestBot provides fuzzing-based support for Python. ## Requirements -1. Python 3.8 or later -2. [Python plugin](https://plugins.jetbrains.com/plugin/631-python) for IntelliJ IDEA -3. IntelliJ IDEA 2022.1 +1. IntelliJ IDEA 2022.2 or later +2. Python 3.8 or later +3. [Python plugin](https://plugins.jetbrains.com/plugin/631-python) for IntelliJ IDEA If you already have a Python project, you usually have no need to install or configure anything else, but if you have trouble with launching UnitTestBot Python, please refer to [advanced requirements section](../utbot-python/docs/CLI.md#requirements). From d4bc2c7bf5919e5df6ec97ce0cb9626f035a1a3d Mon Sep 17 00:00:00 2001 From: Olga Naumenko <64418523+olganaumenko@users.noreply.github.com> Date: Mon, 27 Mar 2023 13:58:28 +0300 Subject: [PATCH 4/4] Minor fixes on IJ IDEA compatibility, npm, and shortcuts --- docs/GoSupport.md | 2 +- docs/JavaScriptSupport.md | 4 +++- docs/PythonSupport.md | 9 ++++----- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/GoSupport.md b/docs/GoSupport.md index 179e1b2c45..04c06ea00a 100644 --- a/docs/GoSupport.md +++ b/docs/GoSupport.md @@ -62,7 +62,7 @@ Go projects automatically. ### Requirements -* IntelliJ IDEA Ultimate 2022.2 or later +* IntelliJ IDEA Ultimate — for compatibility, see [UnitTestBot on JetBrains Marketplace](https://plugins.jetbrains.com/plugin/19445-unittestbot/versions). * Go SDK 1.18 or later * Compatible [Go plugin](https://plugins.jetbrains.com/plugin/9568-go) for IntelliJ IDEA * Properly configured `go.mod` file for the code under test diff --git a/docs/JavaScriptSupport.md b/docs/JavaScriptSupport.md index 48c4412d28..cfafa94e42 100644 --- a/docs/JavaScriptSupport.md +++ b/docs/JavaScriptSupport.md @@ -8,7 +8,7 @@ Now UnitTestBot provides fuzzing-based support for JavaScript. ### Requirements -1. IntelliJ IDEA Ultimate 2022.2 or later +1. IntelliJ IDEA Ultimate — for compatibility, see [UnitTestBot on JetBrains Marketplace](https://plugins.jetbrains.com/plugin/19445-unittestbot/versions). 2. UnitTestBot plugin: please refer to [UnitTestBot user guide](https://github.com/UnitTestBot/UTBotJava/wiki/Install-or-update-plugin). 3. [Node.js 10.0.0 or later](https://nodejs.org/en/download/) (we recommend that you add Node.js to environment variables) @@ -38,6 +38,8 @@ JAR file can be built in [GitHub Actions](https://github.com/UnitTestBot/UTBotJa * _nyc_ 15.1.0 or later: `> npm install -g nyc` * Mocha 10.0.0 or later: `> npm install -g mocha` +_Note:_ for each new project, _npm_ needs internet connection to install the required packages. + ### Generate tests: `generate_js` java -jar utbot-cli.jar generate_js --source="dir/file_with_sources.js" --output="dir/generated_tests.js" diff --git a/docs/PythonSupport.md b/docs/PythonSupport.md index dcaa35236e..eea6d80909 100644 --- a/docs/PythonSupport.md +++ b/docs/PythonSupport.md @@ -6,13 +6,12 @@ Now UnitTestBot provides fuzzing-based support for Python. ## Requirements -1. IntelliJ IDEA 2022.2 or later +1. IntelliJ IDEA — for compatibility, see [UnitTestBot on JetBrains Marketplace](https://plugins.jetbrains.com/plugin/19445-unittestbot/versions). 2. Python 3.8 or later 3. [Python plugin](https://plugins.jetbrains.com/plugin/631-python) for IntelliJ IDEA -If you already have a Python project, you usually have no need to install or configure anything else, but if you have trouble with launching UnitTestBot Python, please refer to [advanced requirements section](../utbot-python/docs/CLI.md#requirements). - -_Note:_ the `com.intellij.modules.python` package should be specified in `/utbot-intellij/resources/plugin.xml` as a dependency for using Python PSI tree. +If you already have a Python project, you usually have no need to install or configure anything else, but if you +have trouble with launching UnitTestBot for Python code, please refer to [advanced requirements section](../utbot-python/docs/CLI.md#requirements). ## How to install and use @@ -23,7 +22,7 @@ To try UnitTestBot Python in your IntelliJ IDEA: **(!) NOTE:** be sure to enable this option for **_each_** project. -4. To generate tests, place the caret at the required function and press **Alt+Shift+U** (**Alt+U, Alt+T** in Ubuntu). +4. To generate tests, place the caret at the required function and press **Alt+Shift+U**. To find the appropriate shortcut for the OS you are using, check the context menu. To use UnitTestBot Python via command-line interface, please refer to the [CLI guide](../utbot-python/docs/CLI.md).