test/README.external

   1 Running the BoringSSL test suite with OpenSSL
   2 =============================================
   3
   4 It is possible to integrate external test suites into OpenSSL's "make test". At
   5 the current time the only supported external suite is the one used by
   6 BoringSSL.
   7
   8 This capability is considered a developer option and may not work on all
   9 platforms.
  10
  11 In order to run the BoringSSL tests with OpenSSL, first checkout the BoringSSL
  12 source code into an appropriate directory:
  13
  14 $ git clone https://boringssl.googlesource.com/boringssl boringssl
  15
  16 The BoringSSL tests are only confirmed to work at a specific commit in the
  17 BoringSSL repository. Later commits may or may not pass the test suite:
  18
  19 $ cd boringssl
  20 $ git checkout 490469f850e
  21
  22 From the OpenSSL source code configure to use the external tests:
  23
  24 $ cd ../openssl
  25 $ ./config enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers \
  26   enable-external-tests
  27
  28 Note that using other config option than those given above may cause the tests
  29 to fail.
  30
  31 Run the OpenSSL tests by providing the path to the BoringSSL test runner in the
  32 BORING_RUNNER_DIR environment variable:
  33
  34 $ BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make test
  35
  36 Note that the test suite may change directory while running so the path provided
  37 should be absolute and not relative to the current working directory.
  38
  39 To see more detailed output you can run just the BoringSSL tests with the
  40 verbose option:
  41
  42 $ VERBOSE=1 BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make \
  43   TESTS="test_external" test
  44
  45
  46 Test failures and suppressions
  47 ==============================
  48
  49 A large number of the BoringSSL tests are known to fail. A test could fail
  50 because of many possible reasons. For example:
  51
  52 - A bug in OpenSSL
  53 - Different interpretations of standards
  54 - Assumptions about the way BoringSSL works that do not apply to OpenSSL
  55 - The test uses APIs added to BoringSSL that are not present in OpenSSL
  56 - etc
  57
  58 In order to provide a "clean" baseline run with all the tests passing a config
  59 file has been provided that suppresses the running of tests that are known to
  60 fail. These suppressions are held in the file "test/ossl_shim/ossl_config.json"
  61 within the OpenSSL source code.
  62
  63 The community is encouraged to contribute patches which reduce the number of
  64 suppressions that are currently present.
  65