Untitled :: Reqstool Documentation

Data

Data Source Types

Reqstool reads data from three (4) different sources:

Local file system
Maven Repository (zip file)
Git Repository
PyPi package

Data Inputs

Reqstool reads both static (created by human) and dynamic data (generated by tool, e.g. Unit Test Reports):

Static Data Inputs

reqstool will look for the following files in the location provided as an argument:

📒 requirements (1)
  📄  manual_verification_results.yml (2)
  📄  requirements.yml (3)
  📄  reqstool_config.yml (4)
  📄  software_verification_cases.yml (5)

1	Content source root
2	See manual_verification_results.yml example
3	See requirements.yml example
4	See reqstool_config.yml example
5	See software_verification_cases.yml example

This means that if you run Reqstool like this:

reqstool report-asciidoc local -p /home/ms001/requirements

Reqstool will then look for the files specified above in the folder that’s specified in the -p argument.

Dynamic Data Inputs

The structure of the files that are generated will differ from language to language (Java vs Python) and from build tool to build tool (Maven vs Gradle).

Currently, only Java using Maven and Python using Hatch or Poetry is supported. A custom layout can be specified in reqstool_config.yml.

The tree below shows where the dynamic files will reside after the Maven project has been built. If you have a configuration where the requirements_annotations.yml and/or svcs_annotations.yml will be placed elsewhere after a successful build, Reqstool will need the path to those files specified in a reqstool_config.yml file. See link above for examples and further information.

Java - Maven

📒 target (1)
  📂 failsafe-reports (2)
  📂 surefire-reports (3)
  📂 generated-sources
    📂 annotations
      📂 resources
        📄 annotations.yml (4)
  📂 generated-test-sources
    📂 test-annotations
      📂 resources
        📄 annotations.yml (5)

1	Maven target root
2	Failsafe Reports root
3	Surefire Reports root
4	See requirements_annotations.yml example
5	See svcs_annotations.yml example

Maven Artifact Zip Directory Structure

In order to produce a Maven Artifact Zip, you will need to incorporate the Reqstool Java Maven Plugin into your build process.

During the build process, the plugin creates a zipfile with the static and dynamic files. The zipfile will be named like [project-id]-[version]-reqstool.zip and will be published under the target/reqstool folder. The plugin will also combine the svcs_annotations.yml and the equirements_annotations.yml into one yml file called annotations.yml.

The Reqstool artifact uploaded as a zip to a Maven repository needs to have the following structure:

📒 requirements  (1)
  📄 manual_verification_results.yml (2)
  📄 requirements.yml (3)
  📄 annotations.yml (4)
  📄 reqstool_config.yml (5)
  📄 software_verification_cases.yml (6)
  📂 test_results
    📂 failsafe (7)
    📂 surefire (8)

1	Content source root
2	See manual_verification_results.yml example
3	See requirements.yml example
4	See reqstool_config.yml example
5	See software_verification_cases.yml example
6	See annotations.yml example
7	Failsafe Reports root
8	Surefire Reports root

Python - Hatch/Poetry

The tree below shows where the dynamic files will reside after a Hatch or Poetry project has been built. If you have a configuration where the annotations.yml will be placed elsewhere after a successful build, Reqstool will need the path to those files specified in a reqstool_config.yml file.

📒 build (1)
  📂 reqstool
    📄 annotations.yml (2)

1	Python build root
2	See requirements_annotations.yml example

Python Package Directory Structure

In order to run reqstool directly on or from the tar.gz file, a custom reqstool_config.yml is added to the tar.gz file by incorporating the Reqstool Python Hatch Plugin or the Reqstool Python Poetry Plugin into your build process.

During the build process, the plugin creates a custom reqstool_config.yml file with paths based on the tar.gz file structure to the static and dynamic files. The reqstool_config.yml file will be located in the root directory of the tar.gz file.

📒 <project_name>.<version>  (1)
  📂 build
    📂 reqstool
      📄 annotations.yml
    📄 test_results.xml
  📂 reqstool
    📄 manual_verification_results.yml
    📄 requirements.yml
    📄 reqstool_config.yml
    📄 software_verification_cases.yml
  📂 src
  📂 tests
  📄 reqstool_config.yml (2)

1	tar.gz file root
2	Generated custom reqstool_config.yml added - See reqstool_config.yml example

What data can exist in what variant?

variant	requirements	annotation (implemention)	annotations (tests)	software verification cases	automated-test	manual verification cases
microservice	yes	yes	yes	yes	yes	yes
system	yes	no	yes	yes	yes	yes
external	yes	no	no	no	no	no

variant

requirements

annotation (implemention)

annotations (tests)

software verification cases

automated-test

manual verification cases

microservice

yes

system

yes

external

yes

Handle imports

In order to import requirements or software verification cases from other sources, requirements.yml supports an import attribute. There are several ways to import content from other sources. This functionality could also be combined with Filters

In order to import content from other sources, add something like the following to the requirements.yml

Local import

To import content from other sources (systems) on the same file system as your current project.

requirements.yml

imports:
  local:
    - path: ../sys-001

Git import

To import content from other sources (systems) using git.

The git key supports a optional value of an env_token, where you could enter a token to authenticate yourself in order to access the repository.

Normally, you should refrain from entering token information explicitly, but rather point towards a secret only accessible through your development/production pipeline or environment variables.

If no authentication is required in order to access the repository, the field env_token can be omitted

requirements.yml

imports:
  git:
    - url: https://github.com/Luftfartsverket/reqstool-demo
      branch: main
      path: docs/reqstool
      env_token: SECRET_TOKEN

Maven import

To import content from other sources (systems) using Maven.

requirements.yml

imports:
  maven:
    - url: https://maven.pkg.github.com/Luftfartsverket/reqstool-client
      group_id: se.lfv.reqstool.testdata
      artifact_id: reqstool-testdata-test-basic-ms101
      path: ""
      version: 0.0.2

PyPI import

requirements.yml

imports:
  pypi:
    - env_token: PYPI_TOKEN
      url: https://pypi.org/project/reqstool/
      package: reqstool
      version: 0.4.7

Import from different sources

It is also possible to import files from multiple types of sources.

requirements.yml

imports:
  local:
    - path: ../sys-001
  git:
    - url: https://github.com/Luftfartsverket/reqstool-demo
      branch: main
      path: docs/reqstool

Filters

Filters can be applied on both requirements.yml and software_verification_cases.yml in order to exclude or include certain requirements or software verification cases.

requiremens.yml

filters:
  sys-001:
    requirement_ids:
      includes:
        - REQ_sys001_103
        - ext-001:REQ_ext001_101

software_verification_cases.yml

filters:
  sys-001:
    svc_ids:
      includes:
        - SVC_sys001_101
        - SVC_sys001_109

Categories

A requirement is assigned to one, or multiple categories.

requirements.yml

requirements:
  - id: REQ_ms001_101
    title: Title REQ_ms001_101
    significance: may
    description: Description REQ_ms001_101
    rationale: Rationale REQ_ms001_101
    categories: ["maintainability", "functional-suitability"]
    revision: 0.0.1

Categories follow the ISO 25010 0 Product Quality Characteristics.

ISO 25010 Product Quality Characteristics

Functional Suitability: Functional Suitability assesses the degree to which the software provides appropriate functions that meet specified needs under specified conditions. It involves evaluating the completeness and appropriateness of the functions provided by the software.
Performance Efficiency: Performance efficiency evaluates the degree to which the software provides appropriate performance relative to the amount of resources used under specified conditions. It includes considerations such as response time, throughput, and resource utilization.
Compatibility: Compatibility assesses the degree to which the software can exchange information and work together with other systems, products, or environments without requiring special effort. It involves evaluating interoperability and integration capabilities.
Interaction Capability: Describes to which degree a product or system can be interacted with by specified users to exchange information.
Reliability: Reliability refers to the degree to which the software performs specified functions under specified conditions without failure for a specified period of time. It involves assessing the software’s ability to maintain its performance level over time and under varying conditions.
Security: Security refers to the degree to which the software protects information and data from unauthorized access, disclosure, alteration, or destruction. It involves assessing aspects such as confidentiality, integrity, authentication, authorization, and non-repudiation.
Maintainability: Maintainability evaluates the degree to which the software can be modified effectively and efficiently without introducing defects or degrading performance. It involves assessing aspects such as modifiability, analyzability, and testability.
Flexibility: Portability assesses the degree to which the software can be transferred from one environment to another, including the necessary adaptation effort. It involves considerations such as adaptability, installability, and coexistence with other software.
Safety: This characteristic represents the degree to which a product under defined conditions to avoid a state in which human life, health, property, or the environment is endangered.