Cross platform yarn with minimal dependencies
Add documentation to README
Update contribution instructions
Fix execution of "FINALLY" steps

refs

master
browse log

clone

read-only
https://git.sr.ht/~richardipsum/tinyyarn
read/write
git@git.sr.ht:~richardipsum/tinyyarn
tyarn -- Tiny Yarn
==================

Cross platform yarn with minimal dependencies.

This is a minimalist yarn[1] by design,
it is not as featureful as the original,
nor does it do any fancy parallel execution like rsyarn[2].

Tested on Debian GNU/Linux and OpenBSD.

tyarn is a scenario testing tool, it is based on yarn[1],
and supports a similar but more limited set of features and syntax.
tyarn translates scenarios written in a natural language
to implementations written in shell code. For example,

    SCENARIO copy a file
       GIVEN a file F
        WHEN the file F is copied to G
        THEN the file G exists

The scenario above describes a simple test for a copy utility,
the SCENARIO line contains the name of the scenario (which must be unique).

A scenario is composed of a set of steps, at a minimum a scenario must include
at least one WHEN step and at least one THEN step,
though it may also provide more than one of each.
In addition to the mandatory steps a scenario may optionally include ASSUMING,
GIVEN, and FINALLY steps.

GIVEN describes a condition that must be satisfied before
the test can be executed. WHEN describes an instruction that will be executed
as part of the test. THEN is used to make an assertion on the state of the
system once the test instruction(s) in the WHEN section have been executed.

FINALLY steps will be executed at the end of each scenario irrespective
of whether the scenario passed or failed.

The ASSUMING step can be used to state an assertion that must be true in order
for the scenario to be run. If the assertion is false then
the scenario is skipped and will not be executed.
This can be useful for testing on different platforms where you may want to
skip tests that are not supported on the current platform.

A corresponding implementation must be provided for each step,
for example shown below are the implementation steps
for the example scenario given above.

    IMPLEMENTS GIVEN a file F
    touch F

    IMPLEMENTS WHEN the file F is copied to G
    cp F G

    IMPLEMENTS THEN the file G exists
    test -e G

The implementations above are a straight forward mapping from natural
langauge to shell code. Scenario implementations may be paramaterised
using POSIX regular expressions to avoid repetition.
For example, the implementations above can be written as:

    IMPLEMENTS GIVEN a file ([A-Za-z0-9]+)
    touch "$MATCH_1"

    IMPLEMENTS WHEN the file ([A-Za-z0-9]+) is copied to ([A-Za-z0-9]+)
    cp "$MATCH_1" "$MATCH_2"

    IMPLEMENTS THEN the file ([A-Za-z0-9]+) exists
    test -e "$MATCH_1"

For each capture an environment variable MATCH_N is defined,
where N is the nth capture. Written this way the implementations may be
used for any scenario step they are a match for.

Scenarios are executed in a temporary directory,
the environment variable DATADIR is set to
the path of this temporary directory.

Building
--------

To build tinyyarn you need lua5.1, lua5.1 headers, and pkg-config.

On Debian,

    % apt install lua5.1 liblua5.1-0-dev pkg-config

On OpenBSD,

    % pkg_add lua-5.1.5p6

pkg-config is available in ports.

Then run,

    % make

Installation
------------

    % make install

Documentation
-------------

Please see the original yarn project[1] for documentation.

All documentation from the original yarn project should apply,
however tinyyarn does not support PCREs,
it uses POSIX extended regular expressions instead.

Contributing
------------

Please feel welcome to submit patches and bug reports via email
to my public-inbox ~richardipsum/public-inbox@lists.sr.ht
alternatively patches may be submitted in private using the address
found in the git log.

See https://git-send-email.io/ for details on contributing
via email with git.

The archive of my public-inbox can be found at
https://lists.sr.ht/~richardipsum/public-inbox.

[1]: http://git.liw.fi/cmdtest/
[2]: https://git.gitano.org.uk/rsyarn.git/