usages-as-tests - Generate and Run Tests from Usage Examples

Table of Contents

• Aims
• Status and Warnings
• How
• Example Setup
• Usage
• Acknowledgments

Aims

• Make simple testing low-cost and automatable especially during exploratory coding when using Janet.

• Encourage the creation of illustrative examples to help potential users form appropriate mental models.

• Capture developers' original intent as usages during initial development.

Status and Warnings

This is an early stage project. The author uses it in a number of projects though. Be sure to examine the fine print.

How

• Within comment blocks, put expressions / forms to be tested along with brief records of expected values:

  (comment
  
    (- 1 1)
    # =>
    0
  
    )

  Note the use of a single line comment and ⇒ (sometimes referred to as a "test indicator") and a subsequent expression to express an expected return value.

  One might call the form + test indicator and expected value expression a "comment block usage" or "comment block test"

  See Usage / Test Writing Tips for more details.

• Once some setup steps are followed, usages / tests can be executed by: jpm test

Example Setup

Suppose there’s a project directory like:

.
├── my-src-dir
│   └── fun.janet
├── project.janet
└── test
    └── test.janet

1. Decide on a name for the directory to hold comment block tests, e.g. examples, then create a direct subdirectory of the project root directory using the name (e.g. examples).

2. Copy the file test/usages-as-tests.janet from this repository to the target project’s test subdirectory and rename it to examples.janet.

3. Within the examples directory, create at least one file with a comment block usage/test in it (in the example below, the file is named nice-samples.janet).

Now it should look something like:

.
├── examples
│   └── nice-samples.janet
├── my-src-dir
│   └── fun.janet
├── project.janet
└── test
    ├── examples.janet
    └── test.janet

See Details for additional information regarding the various files and directories.

Usage

To run the usages/tests and get a report: jpm test

Add more usages / tests / examples by creating more comment block usages in files that live in an appropriate directory.

Acknowledgments

• andrewchambers - suggestion and explanation

• bakpakin - janet, jpm, helper.janet, path.janet, peg for janet, etc.

• pepe - discussion, One-Shot Power Util Solver ™ motivation, and naming

• pyrmont - discussion and exploration

• rduplain - bringing to light customization of jpm test

• Saikyun - discussion and testing

• srnb@gitlab - suggestion