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/Makefile.  More on this later.
  10
  11
  12 Naming convetions
  13 =================
  14
  15 A test executable is named test/{name}test.c
  16
  17 A test recipe is named test/recipes/{nn}-test_{name}.t, where {nn} is a two
  18 digit number and {name} is a unique name of your choice.
  19
  20 The number {nn} is (somewhat loosely) grouped as follows:
  21
  22 05  individual symmetric cipher algorithms
  23 10  math (bignum)
  24 15  individual asymmetric cipher algorithms
  25 20  openssl enc
  26 25  certificate forms, generation and verification
  27 30  engine and evp
  28 70  PACKET layer
  29 80  "larger" protocols (CA, CMS, OCSP, SSL, TSA)
  30 90  misc
  31
  32
  33 A recipe that just runs a test executable
  34 =========================================
  35
  36 A script that just runs a program looks like this:
  37
  38     #! /usr/bin/perl
  39
  40     use OpenSSL::Test::Simple;
  41
  42     simple_test("test_{name}", "{name}test", "{name}");
  43
  44 {name} is the unique name you have chosen for your test.
  45
  46 The second argument to `simple_test' is the test executable, and `simple_test'
  47 expects it to be located in test/
  48
  49 For documentation on OpenSSL::Test::Simple, do
  50 `perldoc test/testlib/OpenSSL/Test/Simple.pm'.
  51
  52
  53 A recipe that runs a more complex test
  54 ======================================
  55
  56 For more complex tests, you will need to read up on Test::More and
  57 OpenSSL::Test.  Test::More is normally preinstalled, do `man Test::More' for
  58 documentation.  For OpenSSL::Test, do `perldoc test/testlib/OpenSSL/Test.pm'.
  59
  60 A script to start from could be this:
  61
  62     #! /usr/bin/perl
  63
  64     use strict;
  65     use warnings;
  66     use OpenSSL::Test;
  67
  68     setup("test_{name}");
  69
  70     plan tests => 2;                # The number of tests being performed
  71
  72     ok(test1, "test1");
  73     ok(test2, "test1");
  74
  75     sub test1
  76     {
  77         # test feature 1
  78     }
  79
  80     sub test2
  81     {
  82         # test feature 2
  83     }
  84
  85
  86 Changes to test/Makefile
  87 ========================
  88
  89 Whenever a new test involves a new test executable you need to do the
  90 following (at all times, replace {NAME} and {name} with the name of your
  91 test):
  92
  93 * among the variables for test executables at the beginning, add a line like
  94   this:
  95
  96     {NAME}TEST= {name}test
  97
  98 * add `$({NAME}TEST)$(EXE_EXT)' to the assignment of EXE:
  99
 100 * add `$({NAME}TEST).o' to the assignment of OBJ:
 101
 102 * add `$({NAME}TEST).c' to the assignment of SRC:
 103
 104 * add the following lines for building the executable:
 105
 106     $({NAME}TEST)$(EXE_EXT): $({NAME}TEST).o $(DLIBCRYPTO)
 107            @target=$({NAME}TEST); $(BUILD_CMD)