Home

Getting Started

Concepts

Creal is a tool that allows for testing consistency, where output should never change, or rather, it is known how the output should change.

To run, do:

creal my_creal_file.creal

Runners

A creal file is made of a collection of runners. Runners are created in a creal file with actions.

Actions

Actions define runners. See also: Actions

Flags

Flags allow for both enabling and disabling of behaviors of the 'interpreter' and runners. In general, flags aim to allow for finer control on what constitutes a pass or fail. See also: Flags

Interpreter

The creal interpreter dynamically reads and runs your creal file. By default, a fail does not end the program. Creal will continue to run your runners till completion. The interpreter also reads from top down, meaning that any flags set after a runner, will not be used for the previous runners.

Syntax

Runners

Runners in creal follow a syntax comparable to yaml.

Actions

In general, actions are defined as:

<action>: <value>

where action is from Actions.

Output

Output is a special case. It supports to methods of entering a value. The first is a single-line variant, where command and the value you assign to it are in the same line.

command: echo I am a single-line command
output: I am a single-line command

However, many times, a command may create a multi-line output, therefore creal provides a multi-line variant to output. To use, place a | where the value of the single-line command would be. Then, create a newline and write your output their. To signal the end of an output, place a | in a newline.

Tip

Place | at the same indentation level for readability.

command: cat ./Cargo.toml
output: |
[package]
name = "generator.rs"
version = "0.1.0"
        |

New Runner

To create a new runner, you must use the runner separator '---'

Warning

On Strict mode, make sure that a separator is placed at the end of the file. This indicates that your runner definition is complete, otherwise, it is ambiguous.

name: I am runner one
command: echo hello, I am runner one.
---
name: I am runner two
command: echo goodbye, I am the last runner!
---

Flags

Warning

Flags are special because their order and placement can change the behavior of your runners.

To use a flag with its default value, follow this format:

#<flag_name_here>
[[! example !]]
#strict
#verbose=true
name: ...
      ...
---

To disable a flag, do:

#<flag_name_here>=FALSE
[[! example !]]
#verbose=false

With flags, you can enable and disable flags for any runner throughout your file.

#strict
#verbose
[[! active_flags: strict + verbose + default flags !]]
name: test strictly a program
command: my_program --help
output: |
USAGE: my_program [-ab] file
        |
returncode: 1
---
#verbose=false
#always_show_output
[[! active_flags: strict + always_show_output + default flags !]]
name: test linking
command: my_program -a ./link.ini
output: |
Found file '~./link.ini'.
Doing things....
Done in 3.64s.
        |
returncode: 0