byexample

Write snippets of code in your documentation and execute them as regression tests.

View project on GitHub
Sorry, it seems that you cannot see the demo. Another excuse to install byexample and test it by yourself ;)

byexample is…

…a literate programming engine where you mix ordinary text and snippets of code in the same file and then you execute them as regression tests.

Do not "write" tests. Instead, write what you want, what do you expect, make examples of them.

Let byexample turn them into your automated tests.
You can always be sure that the examples are correct and your documentation is up to date!

Currently byexample supports the following languages:

Python Logo

Python

Ruby Logo

Ruby

Bash Logo

Shell

GDB Logo

GDB

Javascript Logo

Javascript

C++ Logo

C/C++

Java Logo

Java

PowerShell Logo

PowerShell

iasm Logo

iasm

Go Logo

Go

Rust Logo

Rust

Usage

You write your documentation with examples in a Markdown or other text file.

Then, you run byexample from the command line selecting which language or languages you want to run: Python, Ruby, Shell and C/C++ to mention a few.

And yes, you can write examples in different languages in the same file. Combine them to combine their strengths and make your life easier.

That’s all. byexample will compare the output of the examples with the expected ones and it will show any difference.

How do I get started?

First, you need to install it:

$ pip install byexample                # install it # byexample: +skip

Or if you prefer, you can install it inside a virtual env.

If you don’t have pip or python installed, check the download page.

That’s it! Now, write a tutorial, a blog or a how-to and put some examples in between (like this web page that you are reading); All the snippets and examples will be collected, executed and checked.

$ byexample -l python,ruby,shell README.md      # run it    # byexample: +skip
[PASS] Pass: <...> Fail: <...> Skip: <...>

Platforms supported

Linux is the preferable choice as it is very well tested.

Since byexample 9.2.1 MacOS is also supported* but the testing is more limited so it may not work in all the cases. Check this FAQ.

You can even run byexample in Windows** using Windows Subsystem for Linux but keep in mind that the testing is even more limited; a native execution in Windows (outside of WSL) is currently not supported.

Linux Logo

Linux

MacOS Logo

MacOS*

Windows Logo

Windows**

License

This project is licensed under GPLv3

$ head -n 2 LICENSE     # byexample: +norm-ws
          GNU GENERAL PUBLIC LICENSE
           Version 3, 29 June 2007

See LICENSE for more details.

Versioning

We use semantic version for the core or engine.

For each module we have the following categorization:

  • experimental: non backward compatibility changes are possible or even removal between versions (even patch versions).
  • provisional: low impact non backward compatibility changes may occur between versions; but in general a change like that will happen only between major versions.
  • stable: non backward compatibility changes, if happen, they will between major versions.
  • deprecated: it will disappear in a future version.
  • unsupported: it may work but currently it is not possible to offer any guarantees. Contributions from the community are needed!

See the latest releases and tags and the changelog

Current version:

$ byexample -V
byexample 10.5.2 (Python <...>) - GNU GPLv3
<...>
Copyright (C) Di Paola Martin - https://byexamples.github.io
<...>