Add #defines for magic numbers in API.
[openssl.git] / 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)