test/README

How to add recipes
==================

For any test that you want to perform, you write a script located in
test/recipes/, named {nn}-test_{name}.t, where {nn} is a two digit number and
{name} is a unique name of your choice.

Please note that if a test involves a new testing executable, you will need to
do some additions in test/Makefile.  More on this later.


Naming conventions
=================

A test executable is named test/{name}test.c

A test recipe is named test/recipes/{nn}-test_{name}.t, where {nn} is a two
digit number and {name} is a unique name of your choice.

The number {nn} is (somewhat loosely) grouped as follows:

00-04  sanity, internal and essential API tests
05-09  individual symmetric cipher algorithms
10-14  math (bignum)
15-19  individual asymmetric cipher algorithms
20-24  openssl commands (some otherwise not tested)
25-29  certificate forms, generation and verification
30-35  engine and evp
60-79  APIs
   70  PACKET layer
80-89  "larger" protocols (CA, CMS, OCSP, SSL, TSA)
90-98  misc
99     most time consuming tests [such as test_fuzz]


A recipe that just runs a test executable
=========================================

A script that just runs a program looks like this:

    #! /usr/bin/perl
    
    use OpenSSL::Test::Simple;
    
    simple_test("test_{name}", "{name}test", "{name}");

{name} is the unique name you have chosen for your test.

The second argument to `simple_test' is the test executable, and `simple_test'
expects it to be located in test/

For documentation on OpenSSL::Test::Simple, do
`perldoc test/testlib/OpenSSL/Test/Simple.pm'.


A recipe that runs a more complex test
======================================

For more complex tests, you will need to read up on Test::More and
OpenSSL::Test.  Test::More is normally preinstalled, do `man Test::More' for
documentation.  For OpenSSL::Test, do `perldoc test/testlib/OpenSSL/Test.pm'.

A script to start from could be this:

    #! /usr/bin/perl
    
    use strict;
    use warnings;
    use OpenSSL::Test;
    
    setup("test_{name}");
    
    plan tests => 2;                # The number of tests being performed
    
    ok(test1, "test1");
    ok(test2, "test1");
    
    sub test1
    {
        # test feature 1
    }
    
    sub test2
    {
        # test feature 2
    }
    

Changes to test/Makefile
========================

Whenever a new test involves a new test executable you need to do the
following (at all times, replace {NAME} and {name} with the name of your
test):

* among the variables for test executables at the beginning, add a line like
  this:

    {NAME}TEST= {name}test

* add `$({NAME}TEST)$(EXE_EXT)' to the assignment of EXE:

* add `$({NAME}TEST).o' to the assignment of OBJ:

* add `$({NAME}TEST).c' to the assignment of SRC:

* add the following lines for building the executable:

    $({NAME}TEST)$(EXE_EXT): $({NAME}TEST).o $(DLIBCRYPTO)
           @target=$({NAME}TEST); $(BUILD_CMD)