babelrts 1.1.6
BastRTS is a tool to perform regression test selection.
License: MIT
Requires Python: >=3.8

# BabelRTS
<a href="https://github.com/GabrieleMaurina/babelRTS" alt="build">
<img src="https://img.shields.io/github/workflow/status/GabrieleMaurina/babelRTS/Python%20package" /></a>
<a href="https://github.com/GabrieleMaurina/babelRTS/releases" alt="version">
<img src="https://img.shields.io/github/v/tag/GabrieleMaurina/babelRTS" /></a>

### Babel Regression Test Selection
##### A tool to perform regression test selection

BabelRTS saves time when testing code!

Given a codebase that has changed, this tool selects which tests are safe to execute. Only tests that involve changed code are selected. Tests that operate over untouched code shouldn't be run, so BabelRTS doesn't select them. Therefore it saves a lot of time when doing regression testing over large projects or with large test suites.

BabelRTS works well with many languages and it is based upon [Dext](https://github.com/GabrieleMaurina/dext "Dext github page"), a tool that extracts file dependencies from code.

Run `python -m babelrts -h` for help.

### Install
[Python](https://www.python.org/ "Python website") >= 3.8 is required.

The installation is done through python's package manager **pip**. Simply run:

`python -m pip install babelrts`

### Usage

BabelRTS can be used as a stand alone module, or trough its API. The basic usage is:

`python -m babelrts [-h] [-v] [-l <lang profile>] [-p <project folder>] [-t <test folder>] [-s <source folder>] [-o [<output>]]`

Optional arguments:
*  -h, &nbsp;&nbsp; --help &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; show help message and exit
*  -v, &nbsp;&nbsp; --verbose &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; increase output verbosity
*  -l &nbsp;&nbsp;&nbsp; \<lang\> [\<lang\> ...] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; set one or more languages (default all)
*  -p &nbsp;&nbsp; \<project folder\> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; set project folder (default "current working directory")
*  -t &nbsp;&nbsp;&nbsp; \<test folder\> [\<test folder\> ...] &nbsp; set one or more test folders relative to \<project folder\> (default same as \<project folder\>)
*  -s &nbsp;&nbsp; \<source folders\>  [\<source folder\> ...] &nbsp; set one or more source folders relative to \<project folder\> (default same as \<project folder\>)
*  -o &nbsp;&nbsp;&nbsp; [\<output\>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; set output file (default "stdout")

### Workflow

The suggested workflow for using BabelRTS that will save time during testing

#### Write code
# &darr;
#### Run BabelRTS
# &darr;
#### Run tests
# &darr;
#### Repeat

### Output

When run, this tool generates, inside the project folder, a new folder named `.babelrts`, which contains 4 files:
* **selected.json** contains a json array with the paths to all the selected test files. This file should be used to instruct the testing utility on performing regression testing
* **hash.json** contains a json object with all the sha1 of all the source files in the codebase
* **dependencies.json** contains a json object with all the file dependencies in the codebase
* **changed.json** contains a json array with all the changed classes since the previous BabelRTS run

### API

BabelRTS API can be used by another script. Simply import `babelrts` to access its functions. Its main API is:
* `main()`, to run the whole module as if it was called in the stand alone option.
* `run(langs, project_folder, test_folders, source_folders, verbose, output)`, to run BabelRTS passing your own arguments
* `rts(langs, project_folder, test_folders, source_folders)`, to run just the rts part

Example: runninf BabelRTS from another script.

```python
#import BabelRTS module
>>> import babelrts

#run BabelRTS with language='java', project_folder='java-design-patterns/adapter/', test_folder='src/test', source_folder='src/main', verbose=False
>>> selected, dependencies, changed, new_hashes, test_files, source_files = babelrts.rts(['java'], 'java-design-patterns/adapter/', ['src/test'], ['src/main'])
```

### Languages

BabelRTS supports many languages out of the box, including:
* C
* C++
* C#
* Erlang
* Java
* Javascript
* Php
* Python
* Ruby
* Rust
* Scala

However many more languages are available. Read [Dext Language Profiles](https://github.com/GabrieleMaurina/dext/blob/master/README.md#language-profiles "Dext Language Profiles github page") for more info.

### Explicit dependencies

In some cases it might be useful to define explicit dependencies so that they are understood by BabelRTS. Explicit dependencies can be defined directly from the code itself. BabelRTS recognizes the keyword "babelrts" followed by the name of a file. Since the programming language of the project tested might not like this keyword, it can be written inside a comment and BabelRTS will still parse it. Here is an example in Java:

MyHandler.java
```java
//babelrts SpecialHandler.Java
```
This line, inside the file `MyHandler.java` indicates a dependency to the file `SpecialHandler.Java`.

In python it would look like this:
```python
#babelrts SpecialHandler.py
```

### How it works

BabelRTS uses hashes to determine which files in a codebase have changed and then selects only tests that involve those files, thus saving a lot of time when running the test suite. The steps performed by BabelTS are:
* hash all source files in a codebase
* compare new hashes with the older ones
* mark any file with different hash as "changed"
* mark any new file as "changed"
* compute graph of dependencies
* select any test marked "changed"
* select any test with at least one dependency marked "changed"
* output selected tests
* store hashes for next run

### Advantages

The advantages of using BabelRTS are:
* it works with many languages
* it's lightweight (just a few scripts)
* it's lightning fast to run (faster than other RTS tools)
* it saves a lot of time when used on large projects with large test suites
* it doesn't require anything beside the code itself (other tools need things like the history of faults, class diagrams, integration with versioning tool...)
* it's customizable