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