leo/tests/README.md

# Leo Test Framework

This directory includes Leo code samples, which are parsed and used as tests by test-framework.

## Structure

Currently, test framework covers only two areas: compiler and parser, tests for both destinations are placed in
matching folders. Third folder - expectations - contains results of test execution which are saved in git and then 
compared to test output.

## Test Structure

Tests can be placed either in `compiler/` or `parser/` directories. Each test is a Leo file with correct (or intentionally 
incorrect) Leo code. What makes Leo file a test is block comment at the top of the file:

```
/*
namespace: Parse
expectation: Pass
*/

circuit X {
    x: u32,
    y: u32,
}
```

This comment contains YAML structure with set of mandatory and optional fields.

## Test Expectations

After first run of the tests, test expectations will be autogenerated and placed under `tests/expectations` directory.
They will contain results of exection in detail (for example, in Compiler tests they include number of constraints and 
output registers).

During next test runs, results of each test are compared to stored expectations, and if stored expectations (say, number
of constaints in Pedersen Hash example) don't match actual results, error will be through and test won't pass. Of course,
there are two possible scenarios:

1. If test has failed because logic was changed intentionally, then expectations need to be deleted. New ones will be
generated instead. And commit or PR should contain changes to expectations as well as to tests or code.
2. If test should pass, then expectations should not be changed or removed.

## Test Configuration

Here is the list of all possible configuration options for compiler and parser tests.

#### namespace

```
- Mandatory: yes
- Namespace: all
- Values: Compile / Parser
```

Only two values are supported: `Parser` and `Compile`, the former is meant to be a parser test, the latter 
is, obviously, compiler test. Mind that it's `Compile` and NOT ~Compiler~. 

In Parser namespace there are additional possible values to this field: `ParseStatement`, `ParseExpression` and `Token`. 
Each one of them allows testing Leo parser on different levels - lexer tokens or just expressions/statements.

Compiler tests always include complete Leo programs.

### expectation

```
- Mandatory: yes
- Namespace: all
- Values: Pass / Fail
```

This setting indicates whether given code is supposed to be run successfuly or we expect failure. Then, if test
was marked as `Pass` and it actually failed, you'll know that something went wrong and test or compiler/parser need
fixing.

### input_file (Compile)

```
- Mandatory: no
- Namespace: Compile
- Values: <input file path>, ...
```

This setting allows using one or multiple input files for Leo program. Program will then be run with every provided input.
See this example:

```
/*
namespace: Compile
expectation: Pass
input_file: 
 - inputs/a_0.in
 - inputs/a_1.in
*/

function main(a: u32) {}
```

### inputs (Compile)

```
- Mandatory: no
- Namespace: Compile
- Values: <input file contents>, ...
```

With this setting you can specify inputs right in the test description. It is useful for not creating too many files for
each single case.

```
/*
namespace: Compile
expectation: Pass
inputs: 
 - first.in: |
    [main]
    a: u32 = 100;
    
    [registers]
    r0: bool = false;
# - second.in: | ....
*/

function main(a: u32) -> bool {
    return a == 100;
}
```

### state_file (Compile)

```
- Mandatory: no
- Namespace: Compile
- Values: <path to state file>
```

This setting allows you to specify state file, which can be accessed in Leo program:

```
/*
namespace: Compile
expectation: Pass
state_file: input/basic.state
input_file: input/basic.in
*/

function main(a: bool) -> bool {
    return a == input.registers.b;
}
```