4.0 KiB
Testing KiCad
Unit tests
KiCad has a limited number of unit tests, which can be used to check that certain functionality works.
Tests are registered using CTest, part of CMake. CTest gathers all the disparate test programs and runs them. Most C++ unit tests are written using the Boost Unit Test framework, but this is not required to add a test to the testing suite.
The test CMake targets generally start with qa_
, the names of the tests
within CTest are the same but without the qa_
prefix.
Running tests
You can run all tests after building with make test
or ctest
. The latter
option allows many CTest options which can be useful, especially in automated
or CI environments.
Running specific tests
To run a specific test executable, you can just run with ctest
or run
the executable directly. Running directly is often the simplest way when
working on a specific test and you want access to the test executable's
arguments. For example:
# run the libcommon tests
cd /path/to/kicad/build
qa/common/qa_common [parameters]
For Boost unit tests, you can see the options for the test with <test> --help
.
Common useful patterns:
<test> -t "Utf8/*"
runs all tests in theUtf8
test suite.<test> -t "Utf8/UniIterNull"
runs only a single test in a specific suite.<test> -l all
adds more verbose debugging to the output.<test> --list_content
lists the test suites and test cases within the test program. You can use these for arguments to-l
.
You can rebuild just a specific test with CMake to avoid rebuilding
everything when working on a small area, e.g. make qa_common
.
Writing Boost tests
Boost unit tests are straightforward to write. Individual test cases can be registered with:
BOOST_AUTO_TEST_CASE( SomeTest )
{
BOOST_CHECK_EQUAL( 1, 1 );
}
There is a range of functions like BOOST_CHECK
, which are documented
here. Using the most specific function is preferred, as that
allows Boost to provide more detailed failures: BOOST_CHECK( foo == bar )
only
reports a mismatch, BOOST_CHECK_EQUAL( foo, bar )
will show the values of
each.
To output debug messages, you can use BOOST_TEST_MESSAGE
in the unit tests,
which will be visible only if you set the -l
parameter to message
or higher.
This colours the text differently to make it stand out from other testing
messages and standard output.
You can also use std::cout
, printf
, wxLogDebug
and so on for debug
messages inside tested functions (i.e. where you don't have access to the Boost
unit test headers). These will always be printed, so take care
to remove them before committing, or they'll show up when KiCad runs normally!
Python modules
The Pcbnew Python modules have some test programs in the qa
directory.
You must have the KICAD_SCRIPTING_MODULES
option on in CMake to
build the modules and enable this target.
The main test script is qa/test.py
and the test units are in
qa/testcases
. All the test units can by run using ctest python
, which
runs test.py
.
You can also run an individual case manually, by making sure the
modules are built, adding them to PYTHONPATH
and running the test
from the source tree:
make pcbnew_python_module
export PYTHONPATH=/path/to/kicad/build/pcbnew
cd /path/to/kicad/source/qa
python2 testcase/test_001_pcb_load.py
Diagnosing segfaults
Although the module is Python, it links against a C++ library (the same one used by KiCad Pcbnew), so it can segfault if the library has a defect.
You can run the tests in GDB to trace this:
$ gdb
(gdb) file python2
(gdb) run testcases/test_001_pcb_load.py
If the test segfaults, you will get a familiar backtrace, just like if you were running pcbnew under GDB.