This README details the ‘Google Test Adapter’ GTA and the ‘Test Adapter for Google Test’ TAfGT, and . These test adapters are Visual Studio extensions that provide test discovery and execution of C++ tests written with the Google Test framework.
Microsoft collaborated with the creators of GTA to fork their project and create ‘Test Adapter for Google Test’. These test adapters share many of the same features and any differences will be explicitly labeled with [TAfGT] or [GTA] in this document. GTA may contain more experimental features, whereas all updates to TAfGT must go through Microsoft’s software development cycle.
VSTest.Console.exe
The adapters can be installed in several ways:
After restarting VS, your tests will be displayed in the Test Explorer at build completion time. If no or not all tests show up, have a look at the troubleshooting section.
There are several different ways to configure the adapter:
.sln
file, and must have the same name as that file, but with extension .gta.runsettings
. E.g., if the solution file's name is Foo.sln
, the settings file must be named Foo.gta.runsettings
.VsTest.Console.exe
via the /Settings
parameter.The format of solution and user settings files is the same: a <GoogleTestAdapterSettings>
node contains the solution settings and the (possibly empty) set of project settings and is itself contained in a <RunSettings>
node (which in the case of user settings files might contain additional, e.g. VS specific settings). In contrast to solution settings, each set of project settings additionally has a regular expression to be evaluated at test discovery and execution time.
The final settings to be used are computed by merging the available settings, vaguely following Visual Studio's approach of configuration inheritance. Merging is done in two stages:
Overall, given a test executable mytests.exe
, the following settings apply to that executable in decreasing priority:
mytests.exe
.mytests.exe
.Note that due to the overriding hierarchy described above, you probably want to provide only a subset of the nodes in your configuration files. For instance, providing the node <DebugMode>true</DebugMode>
in a shared solution settings file will make sure that all sharing developers will run the test adapter with debug output, no matter what the developer's individual settings at Tools/Options/Test Adapter for Google Test are (and unless the developer has selected a test settings file via VS, which would override the solution setting).
For reference, see a settings file AllTestSettings.gta.runsettings containing all available settings, a more realistic solution settings file SampleTests.gta.runsettings as delivered with the SampleTests solution, and a user settings file NonDeterministic.runsettings as used by GTA's end-to-end tests.
The test adapters have full support for traits, which can be assigned to tests in two ways:
<Google Test macro>_TRAITS
, where, obviously, <Google Test macro>
is the name of the according macro in Google Test. Each test can be assigned up to 8 traits.More precisely, traits are assigned to tests in three phases:
.*///Size,Medium
assigns the trait (Size,Medium) to all tests.TEST_P_TRAITS(ParameterizedTests, SimpleTraits, Size, Small)
will make sure that all test instances of test ParameterizedTest.SimpleTraits will be assigned the trait (Size,Small) (and override the Size trait assigned from the first phase)..*\[1.*\]///Size,Large
will make sure that all parameterized tests where the parameter starts with a 1 will be assigned the trait (Size,Large) (and override the traits assigned by phases 1 and 2).Note that traits are assigned in an additive manner within each phase, and in an overriding manner between phases. For instance, if a test is assigned the traits (Author,Foo) and (Author,Bar) in phase 1, the test will have both traits. If the test is also assigned the trait (Author,Baz) in phases 2 or 3, it will only have that trait. See test code for examples.
VSTest.Console.exe
The test adapters can be used to run tests from the command line, which can be done making use of VS's VSTest.Console.exe. They support all the tool's command line options, including /UseVsixExtensions
and /TestAdapterPath
.
Note, however, that VSTest.Console.exe will not make use of TAfGT/GTA solution settings (if the solution containing the tests happens to use such settings). All settings to be used by VSTest.Console.exe need to be passed using the /Settings
command line option. Note also that the $(SolutionDir)
placeholder is neither available in the Test setup/teardown batch file options nor in the Additional test execution parameters option.
The tests to be run can be selected via the /TestCaseFilter
option. Filters need to follow the syntax as described in this blog entry. The adapters support the following test properties:
Additionally, traits can be used in test case filters. E.g., all tests having a Duration
of short
can be executed by means of the filter /TestCaseFilter:"Duration=short"
.
Tests are run sequentially by default. If parallel test execution is enabled, the tests will be distributed to the available cores of your machine. To support parallel test execution, additional command line parameters can be passed to the Google Test executables (note that this feature is not restricted to parallel test execution); they can then be parsed by the test code at run time and e.g. be used to improve test isolation.
This test adapter remembers the durations of the executed tests to improve test scheduling for later test runs. The durations are stored in files with endings .gta.testdurations
- make sure your version control system ignores these files.
Note that since VS 2015 update 1, VS allows for the parallel execution of tests (again); since update 2, Test Explorer has an own Run tests in parallel button, and VsTest.Console.exe suppports a new command line option /Parallel. Neither button nor command line option has any effect on test execution with this test adapter.
If you need to perform some setup or teardown tasks in addition to the setup/teardown methods of your test code, you can do so by configuring test setup/teardown batch files, to which you can pass several values such as solution directory or test directory for exclusive usage of the tests.
None or not all of my tests show up
Switch on
This will show on the test console whether your test executables are found by the adapter. If they are not, you have two options:
..\FooTests.exe
, make sure that a file ..\FooTests.exe.is_google_test
exists.Your test executable can not run with command line option --gtest_list_tests
, e.g. because it crashes. Make sure that your tests can be listed via command line; if they do not, debug your test executable, e.g. by making the according test project the startup project of your solution, and placing a breakpoint at the main method of your test executable.
If your project configuration contains references to DLLs which do not end up in the build directory (e.g. through Project/Properties/Linker/Input/Additional Dependencies), these DLLs will not be found when running your tests. Use option PATH extension to add the directories containing these DLLs to the test executables' PATH variable.
If your project happens to be a makefile project, there's a pitfall which will prevent the adapter from discovering your tests: It appears that when importing a makefile project into VS, the Output setting of the project is populated from the makefile's content. However, if the makefile is edited later on such that the location of the generated test executable changes, VS does not find the test executable any more. One symptom of this is that your project can not be launched any more with F5
. Make sure that the Output setting of the project is consistent with its makefile to avoid this problem.
No source locations and traits are found for my tests
Yes
or Optimize for debugging (/DEBUG)
Generate debug information optimized for sharing and publishing (/DEBUG:FULL)
false
, making the test adapter not parse that information out of the pdb file intentionally. The actual set of options used is potentially composed from VS options, a solution settings file, and a user settings file; the resulting set of options will be logged to the test output window if the Print debug info option is set to true
.The extension is disabled when I start Visual Studio
Please refer to our wiki.
Test Adapter for Google Test is maintained by Microsoft.
The original Google Test Adapter is written and maintained by Christian Soltenborn (main author) and Jonas Gefele (regular contributor).
The first version of GTA was a slightly enhanced C# port of the F# Google Test Runner, written by Markus Lindqvist. We have also learned a lot from the JavaScript test runner Chutzpah, written by Matthew Manela.
GTA has benefited from all kinds of contributions, be it feature requests, bug reports, code snippets, testing of new features and bugfixes, or even pull requests. Most (hopefully all) contributors are mentioned in the according release notes.
Download Details:
Author: Microsoft
Official Github: https://github.com/microsoft/TestAdapterForGoogleTest
License: View license