diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f60e4a0eb0..2a15d6d243 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,15 +17,15 @@ We welcome absolutely everyone. With one big and kind request: please follow the
There are so many ways to contribute. Choose yours and find the relevant short guide below.
-|(1) Choose what you like and check the guideline:| (2) Contribute: |
-|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
-|Reporting a bug| Create a [bug reporting issue](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=bug_report.md&title=) |
-|Suggesting a feature| Create a [feature suggestion issue](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=feature_request.md&title=) |
-|Contributing the code (bug fix or feature implementation)| Create a pull request |
-|Reproducing a reported bug| Comment on the issue |
-|Testing a pull request| Comment on the pull request |
-|Improving documentation| Create an issue
Create a pull request
Comment on issues and PRs |
-|Sharing ideas| Start the [Discussion](https://github.com/UnitTestBot/UTBotJava/discussions) or join the existing one |
+| (1) Choose what you like and check the guideline: | (2) Contribute: |
+|-------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+| [Reporting a bug](#Reporting-a-bug) | Create a [bug reporting issue](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=bug_report.md&title=) |
+| [Requesting a feature](#Requesting-a-feature) | Create a [feature suggestion issue](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=feature_request.md&title=) |
+| [Contributing the code (bug fix or feature implementation)](#Contributing-the-code-(bug-fix-or-feature-implementation)) | Create a pull request |
+| [Reproducing a reported bug](#Reproducing-a-reported-bug) | Comment on the issue |
+| [Testing a pull request](#Testing-a-pull-request) | Comment on the pull request |
+| [Improving documentation](#Improving-documentation) | Create an issue
Create a pull request
Comment on issues and PRs |
+| [Sharing ideas](#Sharing-ideas) | Start the [Discussion](https://github.com/UnitTestBot/UTBotJava/discussions) or join the existing one |
# How to submit a contribution
@@ -114,4 +114,4 @@ We do our best in reviewing, but we can hardly specify the exact timeout for it.
By contributing, you agree that your contributions will be licensed under the [Apache License 2.0](https://github.com/UnitTestBot/UTBotJava/blob/main/LICENSE).
-Feel free to [contact us directly](https://www.utbot.org/contact/) if that's a concern.
\ No newline at end of file
+Feel free to [contact us directly](https://www.utbot.org/about) if that's a concern.
\ No newline at end of file
diff --git a/DEVNOTE.md b/DEVNOTE.md
index a509f5901c..a47be23490 100644
--- a/DEVNOTE.md
+++ b/DEVNOTE.md
@@ -4,7 +4,7 @@
When you have the forked repository on your local machine, you are almost ready to build your own version of UnitTestBot.
-💡 Before you start coding, please check the [system requirements](SystemRequirements.md) and find instructions on
+💡 Before you start coding, please check the [system requirements](https://github.com/UnitTestBot/UTBotJava/wiki/Check-system-requirements) and find instructions on
configuring development environment.
💡 Get to know the [code style](https://github.com/saveourtool/diktat/blob/master/info/guide/diktat-coding-convention.md) we are used to.
diff --git a/README.md b/README.md
index a7ee463b78..c87ec7850a 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@
👉 Visit the [official UnitTestBot website](https://www.utbot.org/).
# What is UnitTestBot?
+
UnitTestBot is the tool for **automated unit test generation** and **precise code analysis**. It produces ready-to-use
test
cases for
@@ -17,6 +18,7 @@ The **symbolic execution engine** paired with a **smart fuzzing technique** cons
UnitTestBot represents all the test summaries in a **human-readable format**. The intelligible test method names and comments help you to control the whole testing process. Test failed? The summary refers you to the related branch or the condition under test.
# Get started
+
Try the **[online demo](https://www.utbot.org/utbot/)** to generate unit tests with one click.
Get to know the **full version** of UnitTestBot plugin with this quick guide:
@@ -25,13 +27,15 @@ Get to know the **full version** of UnitTestBot plugin with this quick guide:
Install UnitTestBot plugin for IntelliJ IDEA
Try the most straightforward path to start using UnitTestBot plugin.
-1. Please check the [system requirements](SystemRequirements.md).
+1. Please check the [system requirements](https://github.com/UnitTestBot/UTBotJava/wiki/Check-system-requirements).
2. Open your IntelliJ IDEA.
-3. Go to **File → Settings... → Plugins → Marketplace**.
+3. Go to **File > Settings... > Plugins > Marketplace**.
4. In the search field type *UnitTestBot* — you'll see the UnitTestBot plugin page.
5. Press the **Install** button and wait until it changes to **Installed**, then click **OK**.
-Now you can find the UnitTestBot plugin enabled in the **File → Settings → Plugins** window.
+Now you can find the UnitTestBot plugin enabled in the **File > Settings > Plugins** window.
+
+Do you want to manually choose the build or to update the plugin? Please refer to [Install or update plugin](https://github.com/UnitTestBot/UTBotJava/wiki/Install-or-update-plugin) in our user guide.
____________
@@ -42,11 +46,15 @@ ____________
Proceed to generating unit tests for the existing Java project. If you don't have one, create it using the [JetBrains tutorial](https://www.jetbrains.com/help/idea/creating-and-running-your-first-java-application.html).
1. Open your Java project in IntelliJ IDEA.
-2. Right-click the required package or a file in the Project tool window, scroll the menu down to the bottom and choose **Create Tests with UTBot...**
-3. In the **Generate tests with UTBot** window tick the classes or methods you'd like to cover with unit tests and press **OK**.
+2. Right-click the required package or a file in the Project tool window, scroll the menu down to the bottom and
+ choose **Generate Tests with UnitTestBot...**
+3. In the **Generate Tests with UnitTestBot** window tick the classes or methods you'd like to cover with unit tests and
+ press **Generate Tests** or **Generate and Run**.
Now you can see the resulting test class or classes in the Editor tool window.
+Need to configure testing framework, mocking strategy or parameterization? Please check all [configuration options](https://github.com/UnitTestBot/UTBotJava/wiki/Fine-tune-test-generation).
+
____________
@@ -73,12 +81,15 @@ What can you do with the output?
3. To *view coverage*:
-Right-click the test class, choose **More Run/Debug → Run ... with Coverage**.
+Right-click the test class, choose **More Run/Debug > Run ... with Coverage**.
+
+Want to know more about test descriptions or SARIF reports? Please learn how to [Get use of test results](https://github.com/UnitTestBot/UTBotJava/wiki/Get-use-of-test-results).
____________
# Contribute to UnitTestBot
+
UnitTestBot is an open source project. We welcome everyone who wants to make UnitTestBot better — introduce a new feature or report a bug. We have only one kind request for our contributors: we expect you to prove the necessity and quality of the suggested changes.
How can you do this? Refer to our [Contributing guide](https://github.com/UnitTestBot/UTBotJava/blob/main/CONTRIBUTING.md).
@@ -88,9 +99,11 @@ Feel free to join the [Discussions](https://github.com/UnitTestBot/UTBotJava/dis
And thank you for your time and effort! ⭐
# Find support
-Having troubles with using UnitTestBot? Contact us [directly](https://www.utbot.org/contact).
+
+Having troubles with using UnitTestBot? Contact us [directly](https://www.utbot.org/about).
# Find more UnitTestBot products
+
You can also try [UnitTestBot](https://github.com/UnitTestBot/UTBotCpp) developed especially for C/C++.
You are welcome to [contribute](https://github.com/UnitTestBot/UTBotCpp/blob/main/CONTRIBUTING.md) to it too!
diff --git a/SystemRequirements.md b/SystemRequirements.md
index 2464bb53bd..2ad3352ef6 100644
--- a/SystemRequirements.md
+++ b/SystemRequirements.md
@@ -4,13 +4,13 @@
### To generate tests with UnitTestBot:
-you have to install IntelliJ IDEA (versions from 2022.1 to 2022.1.4 are supported).
+you have to install IntelliJ IDEA (versions from 2022.1 to 2022.2.2 are supported).
### To contribute to UnitTestBot:
you have to install
-- IntelliJ IDEA (versions from 2022.1 to 2022.1.4 are supported);
+- IntelliJ IDEA (versions from 2022.1 to 2022.2.2 are supported);
- JDK 11;
diff --git a/docs/RD for UnitTestBot.md b/docs/RD for UnitTestBot.md
new file mode 100644
index 0000000000..7b88a2798b
--- /dev/null
+++ b/docs/RD for UnitTestBot.md
@@ -0,0 +1,141 @@
+# RD
+New child process communication involves 3 different things:
+1. Lifetimes
+2. Rd entities
+3. Rdgen
+
+Let's dive in each of them:
+
+## Lifetimes
+
+Imagine an object having some resources that should be freed
+when object dies. For this purpose Java introduced interfaces
+```Closeable\AutoCloseable```. Also, 2 helper functions were introduced: try-with-resources and Kotlin's ```Closeable.use```. There are several problems:
+1. Object's lifetime can be more complicated that ```Closeable.use``` scope.
+2. If function parameter is ```Closeable``` - should you close it?
+3. Multiple closes.
+4. Concurrent closes.
+5. If you have several objects that depends on another object's lifetime - how to correctly close all of them with respect to issues 1-4? How to make it simple, convenient and fast?
+
+And so Lifetime was introduced.
+### Lifetime:
+```Lifetime``` is a class, where you can register callbacks and which can be terminated once, thus executing all registered callbacks.
+
+```Lifetime``` is an abstract class, it's inheritor - ```LifetimeDefinition```. The only difference - only ```LifetimeDefinition``` can be terminated. Though all ```Lifetime``` are instances of ```LifetimeDefinition```, there are some conventions:
+1. Do not cast ```Lifetime``` to ```LifetimeDefinion``` unless you are the one who created ```LifetimeDefinition```.
+2. If you introduce somewhere ```LifetimeDefinition``` - either attach it to another ```Lifetime``` or provide code that terminates it.
+
+Useful ```Lifetime``` methods:
+
+- ```onTermination``` - Executes lambda/closeable when lifetime terminates. If already terminated - executes instantly. Termination will proceed on thread that called ```LifetimeDefinition.terminate()```. Callbacks will be executed in ***reversed order***, that is LIFO - last added callback will be executed first.
+- ```onTerminationIfAlive``` - same as ```OnTermination```, but callback will not be executed if lifetime is not alive.
+- ```executeIfAlive``` - executes lambda if lifetime is alive. This method guarantees that lifetime will not be terminated until lambda completes.
+- ```createdNested``` - creates child LifetimeDefinition that will be terminated if parent does.
+- ```usingNested``` - same as ```createNested```, but like ```Closeable.use``` pattern.
+- ```Eternal``` - lifetime that never terminates.
+- ```Terminated``` - lifetime that already terminated.
+- ```status``` - see [LifetimeStatus.kt](https://github.com/JetBrains/rd/blob/9b806ccc770515f6288c778581c54607420c16a7/rd-kt/rd-core/src/main/kotlin/com/jetbrains/rd/util/lifetime/LifetimeStatus.kt) in RD repo. There are 3 convenient method: ```IsAlive, IsNotAlive, IsTerminated```.
+
+### LifetimeDefinition:
+- ```terminate``` - terminates ```Lifetime``` and calls all callbacks. Sometimes if multiple concurrent terminations occurred - method will return before executing all callbacks because some other thread is doing this.
+
+## Rd
+Rd is a cross-language, cross-platform, light-weight, reactive, one-to-one rpc protocol. Can work either on the same or different machines via internet.
+
+Useful entities:
+- ```Protocol``` - encapsulation of all logic regarding rd communication. All entities should be bound to protocol before using. Contains ```IScheduler``` which executes runnables on different thread.
+- ```RdSignal``` - entity for ___fire and forget___. You can add callback for every received message via ```advise(lifetime, callback)``` method. There are 2 interfaces - ```ISink``` which allows only to advise for messages, and ```ISignal``` which can also ```fire``` events. Also, there is just ```Signal``` class with same behaviour, but without remote communication.
+
+ ___Important___: if you advise and fire from the same process - your callback will receive ___not only___ messages from another process, but also the ones you fire.
+- ```RdProperty``` - stateful property. You can get current value, you can advise - advised callback will be executed on current value and on every change.
+- ```RdCall``` - remote procedure call.
+
+Also there are ```RdSet```, ```RdMap``` and many other.
+
+There is ```async``` property that allows you to ```fire``` entities from any thread. Otherwise you would need to do it from ```Protocol.scheduler``` thread. All rd entities should be at first
+
+## Rdgen
+Generates custom classes and requests which can be bound to protocol and advised. There is special model DSL for it.
+### Model DSL
+Eexample:
+1. [Korifey](https://github.com/korifey/rd_example/blob/main/src/main/kotlin/org/korifey/rd_example/model/Root.kt) - quite simple
+2. [Rider Unity plugin](https://github.com/JetBrains/resharper-unity/tree/net223/rider/protocol/src/main/kotlin/model) - complicated one
+
+First you need to define ```Root``` object - only one instance of each root can be assigned to protocol.
+
+Then there is root extension ```Ext(YourRoot)``` where you can define your own types and model entities. You can assign multiple extensions of root for the protocol. Auxillary structures can be defined as direct fields - they will be also generated.
+
+DSL:
+- ```structdef``` - structure with fields that cannot be bound to protocol, but can be serialized. Can be open for inheritace - ```openstruct```, can be abstract - ```basestruct```. Can have only ```field``` as member.
+- ```classdef``` - class that can be bould to model. Can also have ```property```, ```signal```, ```call``` e.t.c. as members. It is possible to do inheritance - ```openclass```, ```baseclass```.
+- ```interfacedef``` - to define interfaces. Use ```method``` to create signature.
+
+ You can use ```extends``` and ```implements``` to work with inheritance.
+
+ ___N.B.___ - rdgen can generate models also for C# and C++. Their structs and classes have a little different behaviour.
+- Rd entities - only in bindable models(```Ext```, ```classdef```):
+ - ```property```
+ - ```signal```
+ - ```source```
+ - ```sink```
+ - ```array``` and ```immutablelist```
+- Useful properties in dsl entities:
+ - async - as ```async``` in RD entities
+ - docs - provides kdoc/javadoc for generated entity
+### Gradle
+[Example](https://github.com/korifey/rd_example/blob/main/build.gradle)
+
+```RdGenExtension``` configurates Rdgen, useful properties:
+- ```sources``` - folders with dsl .kt files. If not present, scan classpath for inheritors of ```Root``` and ```Ext```.
+- ```hashfile``` - folder to store hash file ```.rdgen``` for incremental generation.
+- ```packages``` - java package names to search toplevels, delimited by ','. Example: ```com.jetbrains.rd.model.nova,com,org```.
+- Configuring model generation with method ```RdGenExtension.generator```:
+ - root - for which root you are declaring this generator
+ - namespace - which namespace should be used in generated source. In kotlin it configures generated packaged name.
+ - directory - where to put generated files.
+ - transform - can be ```symmetric```, ```asis``` and ```reversed```. This allows to configure model interface differently for client-server scenarios.
+
+ P.S. This is legacy from distant past, in 99% of time you should use ```symmetric```. In 1% chance - consult with somebody if you really need another option.
+ - language - can be ```kotlin```, ```cpp``` and ```csharp```.
+
+## UtBot project
+
+There is another gradle project ```utbot-rd``` which contains model sources in ```rdgenModels``` sources. Look for ```org.utbot.rd.models.ProtocolRoot```.
+
+Usefull:
+1. if you need to use rd somewhere - add following dependencies:
+ ```
+ implementation group: 'com.jetbrains.rd', name: 'rd-framework', version: 'actual.version'
+
+ implementation group: 'com.jetbrains.rd', name: 'rd-core', version: 'actual.version'
+ ```
+2. There are some usefull classes to work with processes & rd:
+ - ```LifetimedProcess``` - binds ```Lifetime``` to process. If process dies - lifetime terminates and vice versa. You can terminate lifetime manually - this will destroy process.
+ - ```ProcessWithRdServer``` - also starts Rd server and waits for connection.
+ - ```UtInstrumentationProcess``` - encapsulates logic for preparing child process for executing arbitary commands. Exposes ```protocolModel``` for communicating with child process.
+ - ```ConcreteExecutor``` is convenient wrapper for executing commands and managing resources.
+3. How child communication works:
+ - Choosing free port
+ - Creating child process, passing port as argument
+ - Both processes create protocols and bind model
+ - Child process setups all callbacks
+ - Parent process cannot send messages before child creates protocol, otherwise messages will be lost. So child process needs to signal that he is ready.
+ - Child proces creates special file in temp dir, that is observed by parent process.
+ - When parent process spots file - he deletes it, and then sends special message for preparing child proccess instrumentation
+ - Only then process is ready for executing commands
+4. How to write custom commands for child process
+ - Add new ```call``` in ```ProtocolModel```
+ - Regenerate models
+ - Add callback for new ```call``` in ```ChildProcess.kt```
+ - Use ```ConcreteExecutor.withProcess``` method
+ - ___Important___ - do not add `Rdgen` as implementation dependency, it breaks some `.jar`s as it contains `kotlin-compiler-embeddable`.
+5. Logs
+
+ There is ```UtRdLogger``` where you can configure level via ```log4j2.xml```.
+
+6. Custom protocol marshalling types
+
+ Do not spend time on it until:
+ - Cyclic dependencies removed from UtModels
+ - Kotlinx.serialization is used
+