/ 
outhentic-0.00001
/ README.md

Outhentic

print something into stdout and test

Synopsis

Othentic is a text oriented test framework. Istead of hack into objects and methods it deals with text appeared in STDOUT. It's a blackbox testing framework.

Short story

This is five minutes tutorial on othentic workflow.

# story.pl

print "I am OK\n";
print "I am outhentic";

Story file is just an any perl script print something into STDOUT.

# story.check

  I am OK
  I am outhentic

Story check is a bunch of lines STDOUT should match. Here we require to have I am OK' and I am outhentic' lines in STDOUT.

Othentic provides test runner called `story_check', it finds a story files, runs story files and validates STDOUT against story checks.

  story_check

( TODO: ) Add output of story_check here.

Long story

Here is a step by step description of outhentic project layout.

Project

Ouhtentic project is bunch of related stroies. Every outhentic project needs a directory where all the stuff is placed. Let's create a project to test a simple calculator application:


  mkdir calc-app
  cd calc-app

Stories

Inside a project root directory one may create outhentic stroies. Every stories should be kept under a distinct directory:

  mkdir addition
  mkdir multiplication

Now lets create a stories , this should be files named story.pl:

  # addition/story.pl
  use MyCalc;
  my $calc = MyCalc->new();
  print $calc->add(2,2), "\n";
  print $calc->add(3,3), "\n";

  # multiplication/story.pl
  use MyCalc;
  my $calc = MyCalc->new();
  print $calc->mult(2,3), "\n";
  print $calc->mult(3,4), "\n";

Story checks

Story checks files similiraly should be placed at distinct directories and be named as story.check:

  # addition/story.check
  4
  6
  
  # multiplication/story.check
  6
  12

Story runner workflow

This is detailed explanation of how story runner compiles and then executes stories.

Story_check script consequentially hits two phases when execute stories:

Story to Test::Harness compilation

One important thing about story checksis that internally they are represented as Test::More asserts. This is how it work:

Recalling call-app project with 2 stroies:

addition/(story.pl,story.check)
multiplication/(story.pl,story.check)

Story_check parse every story and the creates a perl test file for it:

addition/story.t
multiplication/story.t

Every story check is converted into the list of the Test::More asserts:

    # addition/story.t
    
    run_story('multiplication/story.pl');
    
    SKIP {
        ok($status,'story stdout matches 4'); 
        ok($status,'story stdout matches 6');
    }

    # multiplication/story.t
    
    run_story('multiplication/story.pl');
    
    SKIP {
        ok($status,'story stdout matches 6'); 
        ok($status,'story stdout matches 12');
    }

This is a time diagram for story runner workflow:

- Hits compilation phase
- For every story found:
    - Calculates story settings comes from various ini files
    - Creates a perl test file at Test::Harness format
- The end of compilation phase
- Hits execution phase - runs \`prove' recursively on a directory with a perl test files
- For every perl test file gets executed:
    - Require story.pm if exists
    - Iterate over Test::More asserts
        - Execute story file and save STDOUT in a STDOUT file
        - Execute Test::More assert against a content of STDOUT file
    - The end of Test::More asserts iterator
- The end of execution phase

TAP

Othentic produces output in TAP format, that means you may use your favorite tap parsers to bring result to another test / reporting systems, follow TAP documentation to get more on this.

Here is example for having output in JUNIT format:

story_check --formatter TAP::Formatter::JUnit

Prove settings

Othentic utilize prove utility to run tests, all prove related parameters are passed as is to prove. Here are some examples:

story_check -Q # don't show anythings unless test summary
story_check -q -s # run prove tests in random and quite mode

Story client

Once othentic is installed you get story_check client at the `PATH':

story_check <project_root_dir> <prove settings>

Examples

There is plenty of examples at ./examples directory

AUTHOR

Aleksei Melezhik

Home Page

https://github.com/melezhik/outhentic

Thanks

- For the LORD giveth wisdom: out of his mouth cometh knowledge and understanding.
(Proverbs 2:6)