| 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. |