From 15269e565427e9025c733c2a8b3d4b6d6c5a3bd3 Mon Sep 17 00:00:00 2001
From: Emilia Kasper <emilia@openssl.org>
Date: Fri, 19 Aug 2016 14:19:32 +0200
Subject: [PATCH] Add more details on how to add a new SSL test

Reviewed-by: Stephen Henson <steve@openssl.org>
---
 test/README.ssltest.md         | 57 +++++++++++++++++++++++-----------
 test/recipes/80-test_ssl_new.t |  6 +++-
 2 files changed, 44 insertions(+), 19 deletions(-)

diff --git a/test/README.ssltest.md b/test/README.ssltest.md
index 4e9c0e1fb3..8923578ef3 100644
--- a/test/README.ssltest.md
+++ b/test/README.ssltest.md
@@ -10,23 +10,7 @@ harness generates the output files on the fly.
 
 However, for verification, we also include checked-in configuration outputs
 corresponding to the default configuration. These testcases live in
-`test/ssl-tests/*.conf` files. Therefore, whenever you're adding or updating a
-generated test, you should run
-
-```
-$ ./config
-$ cd test
-$ TOP=.. perl -I testlib/ generate_ssl_tests.pl ssl-tests/my.conf.in \
-  > ssl-tests/my.conf
-```
-
-where `my.conf.in` is your test input file.
-
-For example, to generate the test cases in `ssl-tests/01-simple.conf.in`, do
-
-```
-$ TOP=.. perl generate_ssl_tests.pl ssl-tests/01-simple.conf.in > ssl-tests/01-simple.conf
-```
+`test/ssl-tests/*.conf` files.
 
 For more details, see `ssl-tests/01-simple.conf.in` for an example.
 
@@ -206,7 +190,44 @@ client => {
 
 ## Adding a test to the test harness
 
-Add your configuration file to `test/recipes/80-test_ssl_new.t`.
+1. Add a new test configuration to `test/ssl-tests`, following the examples of
+   existing `*.conf.in` files (for example, `01-simple.conf.in`).
+
+2. Generate the generated `*.conf` test input file. You can do so by running
+   `generate_ssl_tests.pl`:
+
+```
+$ ./config
+$ cd test
+$ TOP=.. perl -I testlib/ generate_ssl_tests.pl ssl-tests/my.conf.in \
+  > ssl-tests/my.conf
+```
+
+where `my.conf.in` is your test input file.
+
+For example, to generate the test cases in `ssl-tests/01-simple.conf.in`, do
+
+```
+$ TOP=.. perl -I testlib/ generate_ssl_tests.pl ssl-tests/01-simple.conf.in > ssl-tests/01-simple.conf
+```
+
+Alternatively (hackish but simple), you can comment out
+
+```
+unlink glob $tmp_file;
+```
+
+in `test/recipes/80-test_ssl_new.t` and run
+
+```
+$ make TESTS=test_ssl_new test
+```
+
+This will save the generated output in a `*.tmp` file in the build directory.
+
+3. Update the number of tests planned in `test/recipes/80-test_ssl_new.t`. If
+   the test suite has any skip conditions, update those too (see
+   `test/recipes/80-test_ssl_new.t` for details).
 
 ## Running the tests with the test harness
 
diff --git a/test/recipes/80-test_ssl_new.t b/test/recipes/80-test_ssl_new.t
index 7cd38565ea..09db280146 100644
--- a/test/recipes/80-test_ssl_new.t
+++ b/test/recipes/80-test_ssl_new.t
@@ -44,6 +44,8 @@ my $no_npn = disabled("nextprotoneg");
 my $no_ct = disabled("ct");
 my $no_ec = disabled("ec");
 
+# Add your test here if the test conf.in generates test cases and/or
+# expectations dynamically based on the OpenSSL compile-time config.
 my %conf_dependent_tests = (
   "02-protocol-version.conf" => !$is_default_tls,
   "04-client_auth.conf" => !$is_default_tls,
@@ -52,7 +54,9 @@ my %conf_dependent_tests = (
   "11-dtls_resumption.conf" => !$is_default_dtls,
 );
 
-# Default is $no_tls but some tests have different skip conditions.
+# Add your test here if it should be skipped for some compile-time
+# configurations. Default is $no_tls but some tests have different skip
+# conditions.
 my %skip = (
   "07-dtls-protocol-version.conf" => $no_dtls,
   "08-npn.conf" => $no_tls || $no_npn,
-- 
2.25.1