TESTING

   1
   2 Overview
   3 --------
   4
   5 The intel-vaapi-driver uses the Google Test Framework (gtest) for testing the
   6 driver.  Documentation for gtest can be found in the test/gtest/doc/
   7 subdirectory.  The original, upstream gtest project can be found at
   8 https://github.com/google/googletest.
   9
  10 Ideally, driver tests will only verify driver-specific functionality, features
  11 and internal utility functions and concepts.
  12
  13 Developers are expected to write new tests for any new code that they contribute
  14 to the project.  The project maintainers reserve the right to refuse patch
  15 submissions if they are not accompanied by tests, when reasonable, or if a
  16 submission causes existing tests to regress.
  17
  18
  19 Google Test Framework Integration
  20 ---------------------------------
  21
  22 Google Test recommends it be custom compiled for each project that uses it.
  23 Therefore, the intel-vaapi-driver project tracks a subset copy of the Google
  24 Test Framework source code at release 1.8.0 (initially) in a test/gtest/
  25 subdirectory of the project source tree.  The intel-vaapi-driver copy of gtest
  26 will only be updated to new upstream releases (or critical upstream fixes) of
  27 gtest, only if it is necessary.  As of this writing, the last release (1.8.0)
  28 was August 2016, about three years after its previous release.  Thus, there
  29 should be minimal need to update or maintain gtest within the intel-vaapi-driver
  30 project.
  31
  32 Intel-vaapi-driver tests or other project code should *not* be intermixed within
  33 the test/gtest/ subdirectory.  The test/gtest/ subdirectory should only contain
  34 source from the upstream Google Test project to make upgrades simpler.
  35
  36
  37 Building Google Test Framework Library
  38 --------------------------------------
  39
  40 The Google Test Framework is compiled as a convenience library (libgtest.la)
  41 within the intel-vaapi-driver source tree.  The rules to build libgtest.la are
  42 maintained in a custom makefile in the intel-vaapi-driver project tree
  43 (see test/Makefile.am).  The libgtest.la library will be automatically compiled
  44 if the tests are enabled by configuration.
  45
  46
  47 Building Driver Tests
  48 ---------------------
  49
  50 The --enable-tests=[yes|no] configuration option is defined in configure.ac to
  51 enable or disable compilation of libgtest.la and the driver test executable.
  52 The default is disabled.  When the tests are enabled during configuration, the
  53 make command will compile the driver tests and link to libgtest.la and output a
  54 single test/test_i965_drv_video executable.  Hence...
  55
  56     "./autogen.sh --enable-tests && make"
  57
  58 ...is a minimal example of how one might build the driver and its tests.
  59
  60
  61 Writing Driver Tests
  62 --------------------
  63
  64 Intel-vaapi-driver tests are defined in the test/ subdirectory using the Google
  65 Test Framework.  All driver tests that need a VADriverContextP, VADisplay and
  66 etc. should define a test fixture that inherits from the I965TestFixture class
  67 and then use the gtest test fixture macro (TEST_F) to define the test case.  The
  68 I965TestFixture class handles initialization and termination of the i965 driver
  69 context, display, etc.  It also defines various C++ operators to convert to
  70 these types, amongst others.  Additionally, it provides an interface that wraps
  71 various i965 driver functions.  After calling a wrapped function within a test,
  72 the test should check HasFailure() with the appropriate assertion macro since
  73 these wrapper functions may generate fatal or non-fatal test assertions.
  74
  75 The following is a basic example of how to use the I965TestFixture class to
  76 write a test:
  77
  78     #include “i965_test_fixture.h”
  79     #include <vector>
  80     class MyDriverATest : public I965TestFixture
  81     {
  82     public:
  83         virtual void SetUp()
  84         {
  85             I965TestFixture::SetUp();
  86
  87             // do local test SetUp stuff
  88         }
  89         virtual void TearDown()
  90         {
  91             // do local test TearDown stuff
  92
  93             I965TestFixture::TearDown();
  94         }
  95     };
  96
  97     TEST_F(MyDriverATest, test_case_1)
  98     {
  99         ConfigAttribs attribs(
 100             1, {type: VAConfigAttribRTFormat, value: VA_RT_FORMAT_YUV420});
 101
 102         // call I965TestFixture wrapper for i965_CreateConfig
 103         VAConfigID config = this->createConfig(
 104             VAProfileJPEGBaseline, VAEntrypointVLD, attribs);
 105         ASSERT_FALSE(HasFailure()); // abort and fail if wrapper call failed
 106         ASSERT_ID(config); // abort and fail if config id is not valid
 107
 108         // convert I965TestFixture to driver context
 109         VADriverContextP ctx(*this);
 110         ASSERT_PTR(ctx); // abort and fail if invalid pointer
 111
 112         // convert I965TestFixture to display
 113         VADisplay display(*this);
 114
 115         // more testing...
 116     }
 117
 118 To directly test a driver function that is only declared and defined in a .c
 119 implementation file, an extern prototype of that function should be declared and
 120 wrapped in an extern “C” block.  The test/i965_internal_decl.h header does some
 121 of this for you already.
 122
 123 To include a driver's C header file in a C++ test file, the #include should be
 124 wrapped within an extern “C” block.  See test/i965_internal_decl.h for an
 125 example.
 126
 127
 128 Validation/QA
 129 --------------
 130
 131 Validation and QA Teams should compile the test executable and run it directly
 132 from their build tree.  Without any command line options, the executable will
 133 execute all the tests and report the result to the console.  For CI frameworks,
 134 the --gtest_output=xml:test_result.xml command line option can be specified to
 135 have the test results dumped to an xml file that can be processed by the CI
 136 framework.  There are various other predefined gtest command line options that
 137 may also be useful, like test shuffling, repeating, seed, etc. (see --help for
 138 these options).
 139
 140
 141 Distribution
 142 ------------
 143
 144 An intel-vaapi-driver source distribution is generated during `make dist` and
 145 includes the necessary Google Test Framework source code and makefile rules
 146 along with the driver test source code.