test/README

   1 How to add recipes
   2 ==================
   3
   4 For any test that you want to perform, you write a script located in
   5 test/recipes/, named {nn}-test_{name}.t, where {nn} is a two digit number and
   6 {name} is a unique name of your choice.
   7
   8 Please note that if a test involves a new testing executable, you will need to
   9 do some additions in test/build.info. Please refer to the section "Changes to
  10 test/build.info" below.
  11
  12
  13 Naming conventions
  14 =================
  15
  16 A test executable is named test/{name}test.c
  17
  18 A test recipe is named test/recipes/{nn}-test_{name}.t, where {nn} is a two
  19 digit number and {name} is a unique name of your choice.
  20
  21 The number {nn} is (somewhat loosely) grouped as follows:
  22
  23 00-04  sanity, internal and essential API tests
  24 05-09  individual symmetric cipher algorithms
  25 10-14  math (bignum)
  26 15-19  individual asymmetric cipher algorithms
  27 20-24  openssl commands (some otherwise not tested)
  28 25-29  certificate forms, generation and verification
  29 30-35  engine and evp
  30 60-79  APIs
  31    70  PACKET layer
  32 80-89  "larger" protocols (CA, CMS, OCSP, SSL, TSA)
  33 90-98  misc
  34 99     most time consuming tests [such as test_fuzz]
  35
  36
  37 A recipe that just runs a test executable
  38 =========================================
  39
  40 A script that just runs a program looks like this:
  41
  42     #! /usr/bin/perl
  43
  44     use OpenSSL::Test::Simple;
  45
  46     simple_test("test_{name}", "{name}test", "{name}");
  47
  48 {name} is the unique name you have chosen for your test.
  49
  50 The second argument to `simple_test' is the test executable, and `simple_test'
  51 expects it to be located in test/
  52
  53 For documentation on OpenSSL::Test::Simple, do
  54 `perldoc util/perl/OpenSSL/Test/Simple.pm'.
  55
  56
  57 A recipe that runs a more complex test
  58 ======================================
  59
  60 For more complex tests, you will need to read up on Test::More and
  61 OpenSSL::Test.  Test::More is normally preinstalled, do `man Test::More' for
  62 documentation.  For OpenSSL::Test, do `perldoc util/perl/OpenSSL/Test.pm'.
  63
  64 A script to start from could be this:
  65
  66     #! /usr/bin/perl
  67
  68     use strict;
  69     use warnings;
  70     use OpenSSL::Test;
  71
  72     setup("test_{name}");
  73
  74     plan tests => 2;                # The number of tests being performed
  75
  76     ok(test1, "test1");
  77     ok(test2, "test1");
  78
  79     sub test1
  80     {
  81         # test feature 1
  82     }
  83
  84     sub test2
  85     {
  86         # test feature 2
  87     }
  88
  89
  90 Changes to test/build.info
  91 ==========================
  92
  93 Whenever a new test involves a new test executable you need to do the
  94 following (at all times, replace {NAME} and {name} with the name of your
  95 test):
  96
  97 * add {name} to the list of programs under PROGRAMS_NO_INST
  98
  99 * create a three line description of how to build the test, you will have
 100 to modify the include paths and source files if you don't want to use the
 101 basic test framework:
 102
 103     SOURCE[{name}]={name}.c
 104     INCLUDE[{name}]=.. ../include ../apps/include
 105     DEPEND[{name}]=../libcrypto libtestutil.a
 106
 107 Generic form of C test executables
 108 ==================================
 109
 110     #include "testutil.h"
 111
 112     static int my_test(void)
 113     {
 114         int testresult = 0;                 /* Assume the test will fail    */
 115         int observed;
 116
 117         observed = function();              /* Call the code under test     */
 118         if (!TEST_int_eq(observed, 2))      /* Check the result is correct  */
 119             goto end;                       /* Exit on failure - optional   */
 120
 121         testresult = 1;                     /* Mark the test case a success */
 122     end:
 123         cleanup();                          /* Any cleanup you require      */
 124         return testresult;
 125     }
 126
 127     int setup_tests(void)
 128     {
 129         ADD_TEST(my_test);                  /* Add each test separately     */
 130         return 1;                           /* Indicate success             */
 131     }
 132
 133 You should use the TEST_xxx macros provided by testutil.h to test all failure
 134 conditions.  These macros produce an error message in a standard format if the
 135 condition is not met (and nothing if the condition is met).  Additional
 136 information can be presented with the TEST_info macro that takes a printf
 137 format string and arguments.  TEST_error is useful for complicated conditions,
 138 it also takes a printf format string and argument.  In all cases the TEST_xxx
 139 macros are guaranteed to evaluate their arguments exactly once.  This means
 140 that expressions with side effects are allowed as parameters.  Thus,
 141
 142     if (!TEST_ptr(ptr = OPENSSL_malloc(..)))
 143
 144 works fine and can be used in place of:
 145
 146     ptr = OPENSSL_malloc(..);
 147     if (!TEST_ptr(ptr))
 148
 149 The former produces a more meaningful message on failure than the latter.
 150