Skip to main content

Markdown Format

We chose Markdown as the primary test fle format for Scrut, because it is an amazingly simple, yet powerful language that is easily usable for humans. It is already supported by many tools and editors and it lends itself to write documentation and tests in the same location.

A markdown test document differs from a "normal" Markdown only in one way: It contains code blocks that are annotated with the scrut language:

# This is a normal markdown document

```scrut
$ some command
some output
```

👆 code block is a Scrut test case,
   because it is annotated with the `scrut` language.

👇 code block is NOT a Scrut test case,
   because it is not annotated with the `scrut` language.

```python
print("I am a snek")
```

Test Case Anatomy​

A test case in Markdown is structured as follows:

  • shell expressions and output expectations live in the same code-block, that must be annotated with the language scrut
    • The first line of a shell expressions must start with $ (dollar, sign followed by a space), any subsequent with > (closing angle bracket / chevron, followed by a space)
    • All other lines in the code block (including empty ones) that follow the shell expression are considered output expectations
    • Lines starting with # that precede the shell expression are ignored (comments)
    • If an exit code other than 0 is expected, it can be denoted in square brackets [123] once per test case
  • The first line before the code block that is either a paragraph or a header will be used as the title of the test case

Here an example:

This is the title

```scrut
$ command | \
>   other-command
expected output line
another expected output line
[123]
```

Constraints​

The following constraints apply:

  • A markdown document can contain as many test cases as needed (0..n)
  • Each code block in a test case may only have one (1) shell expression (each test case is considered atomic)
  • Code blocks that do not denote a language (or a different language than scrut) will be ignored

With that in mind, consider the following markdown document that contains not only test cases but arbitrary other text and other code blocks. This is idiomatic Scrut markdown document that combines tests and documentation:

# This is just regular markdown

It contains both Scrut tests **and**  abitrary text, including code examples,
that are unrelated to Scrut.

```python
import os

print("This code block ignored by Scrut")
```

## Here is a scrut test

```scrut
$ echo Hello
Hello
```

## Embedded with other documentation

So it's a mix of test and not tests.

Any amount of tests are fine:

```scrut
$ echo World
World
```

Just make sure to write only one [test case](/docs/reference/fundamentals/test-case/) per code-block.
note

If you are testing actual markdown output, be aware that you can embed code blocks in other code blocks, if the outer code block uses one more backtick (opening and closing!) than the embedded one(s). Just have a look at the source code of this document right above this text.

Configuration​

Markdown test documents may contain inline configuration. Read more in Reference > Fundamentals > Inline Configuration.