[thirdparty/openssl.git] / 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:

05  individual symmetric cipher algorithms
10  math (bignum)
15  individual asymmetric cipher algorithms
20  openssl commands (some otherwise not tested)
25  certificate forms, generation and verification
30  engine and evp
70  PACKET layer
80  "larger" protocols (CA, CMS, OCSP, SSL, TSA)
90  misc


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)
Commit	Line	Data
5ab4f893 RL	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
69b86d4b	12	Naming conventions
5ab4f893 RL	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
497f3bf9	25	20 openssl commands (some otherwise not tested)
5ab4f893 RL	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)