Skip to main content

Documentation and specification testing framework

Project description

Main PyPI version

Home page | Getting started

nydok is a combined specification writing and testing framework, for producing consistent and traceable specification documents. It is developed for Computerized Systems Validation in a GAMP 5 / GxP context, but is applicable to any software development process where traceability is important.

Write your requirements and risk assessment alongside your Python code, ensuring 1:1 mapping between requirements and the code you're writing.

It is implemented as a plugin for py.test for running the tests, combined with a CLI for creating reports.

Features

Some notable features are:

  • Lets you write specification documents including requirements as normal Markdown.
  • Keeps track of which requirements are missing test cases.
  • Supports a risk assessment process where you can link mitigations to your requirements.
  • Can generate several types of reports in Markdown format for use in a Computerized System Validation process, such as:
    • Traceability matrix
    • Code review reports (Gitlab)
    • Risk assessment report
    • Test summary report
    • CI pipeline logs report (Gitlab)

Installation

Note! nydok is still under development and hasn't yet had a v1.0.0 release, so expect breaking changes.

To install nydok using pip:

pip install nydok

or using Poetry:

poetry add nydok --group dev

Usage

See documentation for details on how to use nydok, the following is just meant as a quick glimpse of how it works. nydok has a lot more features than what is shown here.

Create a cowsay.spec.md specification file:

# Cowsay functional specification

## Functional requirements

- REQ001: The program must take as input a text string
- REQ002: The program must return a string with a cow in ASCII art, displaying the input text as a speech bubble

and a test_cowsay.py file:

from nydok import testcase
import cowsay


@testcase(["REQ001", "REQ002"])
def test_cowsay():
    assert cowsay("Hello world") == """
     _____________
    < Hello world >
     -------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
    """

Next, run py.test to check the specification:

$ py.test --nydok-output nydok.json cowsay/
========================= test session starts =========================
platform linux -- Python 3.10.6, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /project
plugins: nydok-0.8.0
collected 3 items

cowsay/test_cowsay.py::test_cowsay PASSED                       [ 33%]
cowsay/cowsay.spec.md::REQ001 PASSED                            [ 66%]
cowsay/cowsay.spec.md::REQ002 PASSED                            [100%]

========================== 3 passed in 0.01s ==========================

Each requirement listed in the specification file is counted as a test item, and will pass or fail depending on it's test case.

Finally, run nydok report to generate reports.

As an example, to create a traceability matrix, run:

$ nydok report traceability-matrix nydok.json

to generate the following Markdown table:

ID Description References Test case
REQ001 The program must take as input a text string TC001
REQ002 The program must return a string with a cow in ASCII art, displaying the input text as a speech bubble TC001

License

nydok is released under the MIT license. See LICENSE for details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nydok-0.8.2.tar.gz (17.9 kB view hashes)

Uploaded Source

Built Distribution

nydok-0.8.2-py3-none-any.whl (20.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page