judge-gen - Generate and Run Tests from Usage Examples

Table of Contents

• Aims
• Status and Warnings
• How
• Example Setup
• Usage
• Sample Repositories
• 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.

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 ⇒ to express an expected return value.

  One might call the form + expected value comment a "comment block test".

  See Usage / Test Writing Tips for more details.

• Once some setup steps are followed, tests can be run 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.

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

3. Create a direct subdirectory of the project root directory named examples to house comment block tests.

4. Within the examples directory, create at least one file with a comment block test in it.

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 tests and get a report: jpm test

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

Sample Repositories

This repository can serve as an example, but here are some others:

• clojure-peg

• detect-clj-ns

• janet-zip

• mal-peg

• margaret

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