This repostitory contains a Python implementation of the functions around the causality in requirements artifacts (CiRA) initiative. The initiative is centered around the notion of causal requirements and causality extraction for automatic test case generation.
The main pipeline offers the following functionality:
- Classifying a sentence regarding its causality (binary classification: causal/non-causal)
- Labeling the elements of a causal relationship within a causal sentence.
- Transforming a labeled sentence into a cause-effect graph representing the causal relationship.
- Transforming a cause-effect graph into a minimal set of test cases (test suite) asserting the behavior implied by the sentence.
The features can be visualized considering the following example sentence:
If an error is present and the debugger is active or an exception is triggered then a log entry will be created.
This contrived requirement represents a causal relationship between four events, hence the binary classifier will classify it as causal.
Labeling the sentence will produce a list of labels that can be visualized as follows (visualization using labviz):
Every label consists of a type (e.g., Cause1, Variable), and a begin and end index, representing the characters it spans across. These labels make explicit, which role each part of the sentence takes in the causal relationship.
Based on these labels, the causal relationship can be reconstructed in the form of a cause-effect graph (visualization using labviz):
The cause-effect graph represents the causal relationship implied by the natural language sentence, but is much easier to process.
A minimal set of test cases covering the requirement can be derived from this cause-effect graph:
| id | an exception | an error | the debugger | a log entry |
|---|---|---|---|---|
| 1 | is triggered | not is present | is active | will be created |
| 2 | is triggered | is present | not is active | will be created |
| 3 | not is triggered | is present | is active | will be created |
| 4 | not is triggered | not is present | is active | not will be created |
| 5 | not is triggered | is present | not is active | not will be created |
The first three columns after the index represent the input values and the last column represents the expected outcome. These five test cases completely cover the requirement from a combinatorial standpoint.
This package is built and tested using Python 3.10.0. To use the CiRA pipeline locally, perform the following steps:
- Make sure the Rust compiler is installed on your system, as the
tokenizerpackage depends on it. - Install all required dependencies via
pip3 install -e ".[dev]"orpip3 install -e .if you only want production dependencies. - Download and unzip the pre-trained classification and labeling models or use the
download-models.shscript. - Create a
.envfile and specify the variablesMODEL_CLASSIFICATIONandMODEL_LABELINGwith the location of the respective models.
You can develop inside a Docker container using a pre-build image that contains all dependencies and the recommended classification and labeling models.
For this setup, you need
Use then the Remote-Containers: Open Workspace in Container... command to open the project inside the container.
You can find detailed information about the development container setup here.
To use the CiRA pipeline, instantiate a src.cira.CiRAConverter object and specify the location of the pre-trained models. Then, use the high-level functionality as shown in the demonstration.ipynb file.
The CiRA functionality can also be provided by a single Docker container based on Dockerfile.
Build and run the Docker container via docker compose up.
CiRA's functionality can then be accessed at localhost:8080.
Check localhost:8080\docs while the container is running to access the specification of the API.
The application Docker image and the development container setup are based on the cira-dev image and is present in this repository's packages section.
Run all tests via pytest.