Chunk 12 of CMP contribution to OpenSSL: CLI-based high-level tests

[openssl.git] / test / README.ssltest.md

diff --git a/test/README.ssltest.md b/test/README.ssltest.md
index 42a25189a2fb3ff071cac7ead714e426c2fe8db1..6ae10fdc181013fac125bcfa1bf91427f9a5fe47 100644 (file)
--- a/test/README.ssltest.md
+++ b/test/README.ssltest.md
@@ -1,4 +1,5 @@
-# SSL tests
+SSL tests
+=========
 
 SSL testcases are configured in the `ssl-tests` directory.
 
@@ -14,20 +15,19 @@ corresponding to the default configuration. These testcases live in
 
 For more details, see `ssl-tests/01-simple.cnf.in` for an example.
 
-## Configuring the test
+Configuring the test
+--------------------
 
 First, give your test a name. The names do not have to be unique.
 
 An example test input looks like this:
 
-```
     {
         name => "test-default",
         server => { "CipherString" => "DEFAULT" },
         client => { "CipherString" => "DEFAULT" },
         test   => { "ExpectedResult" => "Success" },
     }
-```
 
 The test section supports the following options
 
@@ -111,19 +111,18 @@ handshake.
   If this is "empty" the list is expected to be empty otherwise it is a file
   of certificates whose subject names form the list.
 
-## Configuring the client and server
+Configuring the client and server
+---------------------------------
 
 The client and server configurations can be any valid `SSL_CTX`
 configurations. For details, see the manpages for `SSL_CONF_cmd`.
 
 Give your configurations as a dictionary of CONF commands, e.g.
 
-```
-server => {
-    "CipherString" => "DEFAULT",
-    "MinProtocol" => "TLSv1",
-}
-```
+    server => {
+        "CipherString" => "DEFAULT",
+        "MinProtocol" => "TLSv1",
+    }
 
 The following sections may optionally be defined:
 
@@ -146,14 +145,12 @@ The following sections may optionally be defined:
 Additional handshake settings can be configured in the `extra` section of each
 client and server:
 
-```
-client => {
-    "CipherString" => "DEFAULT",
-    extra => {
-        "ServerName" => "server2",
+    client => {
+        "CipherString" => "DEFAULT",
+        extra => {
+            "ServerName" => "server2",
+        }
     }
-}
-```
 
 #### Supported client-side options
 
@@ -202,21 +199,18 @@ automatically. Server certificate verification is requested by default.
 
 You can override these options by redefining them:
 
-```
-client => {
-    "VerifyCAFile" => "/path/to/custom/file"
-}
-```
+    client => {
+        "VerifyCAFile" => "/path/to/custom/file"
+    }
 
 or by deleting them
 
-```
-client => {
-    "VerifyCAFile" => undef
-}
-```
+    client => {
+        "VerifyCAFile" => undef
+    }
 
-## Adding a test to the test harness
+Adding a test to the test harness
+---------------------------------
 
 1. Add a new test configuration to `test/ssl-tests`, following the examples of
    existing `*.cnf.in` files (for example, `01-simple.cnf.in`).
@@ -224,33 +218,26 @@ client => {
 2. Generate the generated `*.cnf` test input file. You can do so by running
    `generate_ssl_tests.pl`:
 
-```
-$ ./config
-$ cd test
-$ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl ssl-tests/my.cnf.in default \
-  > ssl-tests/my.cnf
-```
+    $ ./config
+    $ cd test
+    $ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl \
+      ssl-tests/my.cnf.in default > ssl-tests/my.cnf
 
 where `my.cnf.in` is your test input file and `default` is the provider to use.
 For all the pre-generated test files you should use the default provider.
 
 For example, to generate the test cases in `ssl-tests/01-simple.cnf.in`, do
 
-```
-$ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl ssl-tests/01-simple.cnf.in default > ssl-tests/01-simple.cnf
-```
+    $ TOP=.. perl -I ../util/perl/ generate_ssl_tests.pl \
+      ssl-tests/01-simple.cnf.in default > ssl-tests/01-simple.cnf
 
 Alternatively (hackish but simple), you can comment out
 
-```
-unlink glob $tmp_file;
-```
+    unlink glob $tmp_file;
 
 in `test/recipes/80-test_ssl_new.t` and run
 
-```
-$ make TESTS=test_ssl_new test
-```
+    $ make TESTS=test_ssl_new test
 
 This will save the generated output in a `*.tmp` file in the build directory.
 
@@ -258,13 +245,13 @@ This will save the generated output in a `*.tmp` file in the build directory.
    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
+Running the tests with the test harness
+---------------------------------------
 
-```
-HARNESS_VERBOSE=yes make TESTS=test_ssl_new test
-```
+    HARNESS_VERBOSE=yes make TESTS=test_ssl_new test
 
-## Running a test manually
+Running a test manually
+-----------------------
 
 These steps are only needed during development. End users should run `make test`
 or follow the instructions above to run the SSL test suite.
@@ -273,17 +260,13 @@ To run an SSL test manually from the command line, the `TEST_CERTS_DIR`
 environment variable to point to the location of the certs. E.g., from the root
 OpenSSL directory, do
 
-```
-$ CTLOG_FILE=test/ct/log_list.cnf TEST_CERTS_DIR=test/certs test/ssl_test \
-  test/ssl-tests/01-simple.cnf
-```
+    $ CTLOG_FILE=test/ct/log_list.cnf TEST_CERTS_DIR=test/certs test/ssl_test \
+      test/ssl-tests/01-simple.cnf
 
 or for shared builds
 
-```
-$ CTLOG_FILE=test/ct/log_list.cnf  TEST_CERTS_DIR=test/certs \
-  util/wrap.pl test/ssl_test test/ssl-tests/01-simple.cnf
-```
+    $ CTLOG_FILE=test/ct/log_list.cnf  TEST_CERTS_DIR=test/certs \
+      util/wrap.pl test/ssl_test test/ssl-tests/01-simple.cnf
 
 Note that the test expectations sometimes depend on the Configure settings. For
 example, the negotiated protocol depends on the set of available (enabled)