[Libva] [PATCH RFC intel-driver 11/11] test: add TESTING readme file
U. Artie Eoff
ullysses.a.eoff at intel.com
Thu Sep 1 19:59:45 UTC 2016
Add a TESTING readme file to describe the design and usage
of the libva-intel-driver tests.
Signed-off-by: U. Artie Eoff <ullysses.a.eoff at intel.com>
---
README | 7 +++-
TESTING | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 153 insertions(+), 1 deletion(-)
create mode 100644 TESTING
diff --git a/README b/README
index cf3ac8e97e57..0d1f42e50634 100644
--- a/README
+++ b/README
@@ -2,7 +2,7 @@
libva-intel-driver
VA driver for Intel G45 & HD Graphics family
- Copyright (C) 2009-2015 Intel Corporation
+ Copyright (C) 2009-2016 Intel Corporation
License
@@ -50,3 +50,8 @@ Requirements
------------
libva >= 1.7.0
+
+Testing
+-------
+
+Please read the TESTING file available in this package.
diff --git a/TESTING b/TESTING
new file mode 100644
index 000000000000..44f045096e89
--- /dev/null
+++ b/TESTING
@@ -0,0 +1,147 @@
+
+Overview
+--------
+
+The libva-intel-driver uses the Google Test Framework (gtest) for testing the
+driver. Documentation for gtest can be found in the test/gtest/doc/
+subdirectory. The original, upstream gtest project can be found at
+https://github.com/google/googletest.
+
+Ideally, driver tests will only verify driver-specific functionality, features
+and internal utility functions and concepts.
+
+Developers are expected to write new tests for any new code that they contribute
+to the project. The project maintainers reserve the right to refuse patch
+submissions if they are not accompanied by tests, when reasonable, or if a
+submission causes existing tests to regress.
+
+
+Google Test Framework Integration
+---------------------------------
+
+Google Test recommends it be custom compiled for each project that uses it.
+Therefore, the libva-intel-driver project tracks a subset copy of the Google
+Test Framework source code at release 1.8.0 (initially) in a test/gtest/
+subdirectory of the project source tree. The libva-intel-driver copy of gtest
+will only be updated to new upstream releases (or critical upstream fixes) of
+gtest, only if it is necessary. As of this writing, the last release (1.8.0)
+was August 2016, about three years after its previous release. Thus, there
+should be minimal need to update or maintain gtest within the intel-driver
+project.
+
+Libva-intel-driver tests or other project code should *not* be intermixed within
+the test/gtest/ subdirectory. The test/gtest/ subdirectory should only contain
+source from the upstream Google Test project to make upgrades simpler.
+
+
+Building Google Test Framework Library
+--------------------------------------
+
+The Google Test Framework is compiled as a convenience library (libgtest.la)
+within the libva-intel-driver source tree. The rules to build libgtest.la are
+maintained in a custom makefile in the libva-intel-driver project tree
+(see test/Makefile.am). The libgtest.la library will be automatically compiled
+if the tests are enabled by configuration.
+
+
+Building Driver Tests
+---------------------
+
+The --enable-tests=[yes|no] configuration option is defined in configure.ac to
+enable or disable compilation of libgtest.la and the driver test executable.
+The default is disabled. When the tests are enabled during configuration, the
+make command will compile the driver tests and link to libgtest.la and output a
+single test/test_i965_drv_video executable. Hence...
+
+ "./autogen.sh --enable-tests && make"
+
+...is a minimal example of how one might build the driver and its tests.
+
+
+Writing Driver Tests
+--------------------
+
+Libva-intel-driver tests are defined in the test/ subdirectory using the Google
+Test Framework. All driver tests that need a VADriverContextP, VADisplay and
+etc. should define a test fixture that inherits from the I965TestFixture class
+and then use the gtest test fixture macro (TEST_F) to define the test case. The
+I965TestFixture class handles initialization and termination of the i965 driver
+context, display, etc. It also defines various C++ operators to convert to
+these types, amongst others. Additionally, it provides an interface that wraps
+various i965 driver functions. After calling a wrapped function within a test,
+the test should check HasFailure() with the appropriate assertion macro since
+these wrapper functions may generate fatal or non-fatal test assertions.
+
+The following is a basic example of how to use the I965TestFixture class to
+write a test:
+
+ #include “i965_test_fixture.h”
+ #include <vector>
+ class MyDriverATest : public I965TestFixture
+ {
+ public:
+ virtual void SetUp()
+ {
+ I965TestFixture::SetUp();
+
+ // do local test SetUp stuff
+ }
+ virtual void TearDown()
+ {
+ // do local test TearDown stuff
+
+ I965TestFixture::TearDown();
+ }
+ };
+
+ TEST_F(MyDriverATest, test_case_1)
+ {
+ ConfigAttribs attribs(
+ 1, {type: VAConfigAttribRTFormat, value: VA_RT_FORMAT_YUV420});
+
+ // call I965TestFixture wrapper for i965_CreateConfig
+ VAConfigID config = this->createConfig(
+ VAProfileJPEGBaseline, VAEntrypointVLD, attribs);
+ ASSERT_FALSE(HasFailure()); // abort and fail if wrapper call failed
+ ASSERT_ID(config); // abort and fail if config id is not valid
+
+ // convert I965TestFixture to driver context
+ VADriverContextP ctx(*this);
+ ASSERT_PTR(ctx); // abort and fail if invalid pointer
+
+ // convert I965TestFixture to display
+ VADisplay display(*this);
+
+ // more testing...
+ }
+
+To directly test a driver function that is only declared and defined in a .c
+implementation file, an extern prototype of that function should be declared and
+wrapped in an extern “C” block. The test/i965_internal_decl.h header does some
+of this for you already.
+
+To include a driver's C header file in a C++ test file, the #include should be
+wrapped within an extern “C” block. See test/i965_internal_decl.h for an
+example.
+
+
+Validation/QA
+--------------
+
+Validation and QA Teams should compile the test executable and run it directly
+from their build tree. Without any command line options, the executable will
+execute all the tests and report the result to the console. For CI frameworks,
+the --gtest_output=xml:test_result.xml command line option can be specified to
+have the test results dumped to an xml file that can be processed by the CI
+framework. There are various other predefined gtest command line options that
+may also be useful, like test shuffling, repeating, seed, etc. (see --help for
+these options).
+
+
+Distribution
+------------
+
+A libva-intel-driver source distribution is generated during `make dist` and
+includes the necessary Google Test Framework source code and makefile rules
+along with the driver test source code.
+
--
2.4.11
More information about the Libva
mailing list