From f4676a0329d8b665a0214c214d17dc12f0589634 Mon Sep 17 00:00:00 2001 From: Olga Naumenko <64418523+olganaumenko@users.noreply.github.com> Date: Fri, 7 Oct 2022 13:45:32 +0300 Subject: [PATCH 1/2] Minor doc updates: SysReq, UI labels, contacts, links to user guide, RD --- CONTRIBUTING.md | 2 +- DEVNOTE.md | 2 +- README.md | 27 +++++-- SystemRequirements.md | 4 +- docs/RD for UnitTestBot.md | 142 +++++++++++++++++++++++++++++++++++++ 5 files changed, 166 insertions(+), 11 deletions(-) create mode 100644 docs/RD for UnitTestBot.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f60e4a0eb0..dcf4eeafac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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..bd60581f7b --- /dev/null +++ b/docs/RD for UnitTestBot.md @@ -0,0 +1,142 @@ +# 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 + + P.S. see [this](https://confluence-msc.rnd.huawei.com/pages/viewpage.action?pageId=185665825) \ No newline at end of file From d3208d3b63d5f16e211e385a003d3fe4c7b29790 Mon Sep 17 00:00:00 2001 From: Olga Naumenko <64418523+olganaumenko@users.noreply.github.com> Date: Wed, 12 Oct 2022 18:19:16 +0300 Subject: [PATCH 2/2] Minor doc updates: RD - link removed, Contributing - inner links added --- CONTRIBUTING.md | 18 +++++++++--------- docs/RD for UnitTestBot.md | 1 - 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dcf4eeafac..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 diff --git a/docs/RD for UnitTestBot.md b/docs/RD for UnitTestBot.md index bd60581f7b..7b88a2798b 100644 --- a/docs/RD for UnitTestBot.md +++ b/docs/RD for UnitTestBot.md @@ -139,4 +139,3 @@ Usefull: - Cyclic dependencies removed from UtModels - Kotlinx.serialization is used - P.S. see [this](https://confluence-msc.rnd.huawei.com/pages/viewpage.action?pageId=185665825) \ No newline at end of file