Development Knowledge Base

Building, testing, debugging

The Google Test Adapter solution is configured such that two different adapters can be built from it: the original Google Test Adapter (GTA) and Microsoft's Test Adapter for Google Test (TAfGT). Of course, the rational behind this is that the majority of the code can be shared between the two adapters.

As such, two flavors of the solution exist; the flavor to be built is configured via file TestAdapterFlavor.props.

However, to make maintenance as well as contributors life easier, the TAfGT artifacts have been removed from the solution (not from the repository) for now. As soon as MS has merged the current GTA state into the TAfGT repository, the build instructions as archived below will be in place again. At that point in time, the following commits have to be reverted: df5a6b6, 10fd131

Initial setup

To build the test adapter, a one-time setup has to be performed:

Check whether the paths defined at the beginning of the build_preparation.bat file are correct on your machine.
Make sure NuGet is on the path.
Run build_preparation.bat from its folder. This will
1. restore the solution's NuGet packages,
2. copy the msdia140.dll DLLs from Visual Studio's DIA SDK folder into the according solution folders,
3. and build the CLR assembly for DIA SDK.
If you test build for Visual Studio 2017 and your installation is not either in C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise or C:\Program Files (x86)\Microsoft Visual Studio\2017\Community, the environment variable GTA_TESTS_VS2017 needs to be set to the correct path.

Afterwards, the solution can be opened with Visual Studio 2017 or later; it should build without errors, and tests should all pass.

Executing the tests

Many of the tests depend on the second solution SampleTests, which contains a couple of Google Test tests. Before any of the tests can be run, this second solution needs to be built with several configurations; this is done by the pre-build event of project Tests/SampleTests/SampleTestsBuilder.

For manually testing GTA, just start the GTA solution: A development instance of Visual Studio will be started with GTA installed. Use this instance to open the SampleTests solution (or any other solution containing Google Test tests).

Debugging GTA

Projects TestAdapter and VsPackage.GTA have debugging options pre-configured. TestAdapter will run the tests in the SampleTests solution using the command line tool for running tests (vstest.console.exe). VsPackage will start an experimental instance of Visual Studio (devenv.exe) having the current build of GTA deployed.

Note that different parts of GTA will run in different processes which are spawned on demand:

devenv.exe (running in IDE: RunSettingsService, GoogleTestExtensionOptionsPage and GlobalRunSettingsProvider)
vstest.console.exe (running from command line: RunSettingsService)
te.processhost.managed.exe (platform X86: TestDiscoverer and TestExecutor)
vstest.discoveryengine.exe (platform X64: TestDiscoverer)
vstest.executionengine.exe (platform X64: TestExecutor)

A convenient way to get your debugger attached is to use Microsoft's Child Process Debugging Power Tool. We have the GoogleTestAdapter.ChildProcessDbgSettings already precofigured for you. Alternatively, you can add System.Diagnostics.Debugger.Break() statements in places of interest.

Contributions

Pull requests (against the develop branch) are welcome and will be reviewed carefully. Please make sure to include tests demonstrating the bug you fixed or covering the added functionality.

Branching strategy

The GTA project follows a simple branching strategy:

Releases are created from master
Development is done on develop
Bugfixes are done on master and merged into develop
Feature branches are based on develop (and only merged into that branch)
- Naming scheme: #{issue number}_{feature name/description}
- Finite lifetime (in contrast to masterand develop)
- For local branches, rebasing is preferred (but not required)
- Branches are merged without squashing
Acceptance testing happens on develop
Releases are created by merging develop into master

Release steps

Releases are created from master branch. A commit results in a release deployed on GitHub if that commit is tagged in a certain way:

The tag needs to be lightweight
The tag needs to point at the same commit as the master branch

To produce a release, follow the steps below.

Change version in appveyor.yml, VSPackage.nuspec, and README.md (e.g., 1.0.2)
Update VS Marketplace count in README.md
Add release notes file to VsPackage/Resources/ReleaseNotes if it does not yet exist

For the links to work on both GitHub and in our release notes dialog, make sure to only use absolute links (e.g. [#48](https://github.com/csoltenborn/GoogleTestAdapter/issues/48) instead of #48)

Add version and date to VsPackage/ReleaseNotes/History.cs
Commit
Create tag as described above with name v1.0.2

SourceTree: Check "Lightweight tag" at advanced tag options
Console: git tag v1.0.2

Push master branch with tag

SourceTree: Check "Push all tags" at push dialog

Wait for AppVeyor build to finish (which deploys the release to GitHub)
Check release on GitHub, publish release if everything is fine
Download resulting vsix file and upload it to the VS Gallery
If necessary: update description at VS Gallery

After pushing, README.md points to a not yet existing release - make sure to finish the rest of the process asap.

Lost and found

Generating fused Google Test source

Change to directory googletest\googletest\scripts
Execute command python fuse_gtest_files.py fused-src

Initial setup (archived until MS has merged current GTA state into the TAfGT repository)

To build the test adapter, a one-time setup has to be performed. The TAfGT setup can be found here. For the GTA flavor, proceed as follows:

Check whether the paths defined at the beginning of the build_preparation.bat file are correct on your machine.
Run build_preparation.bat from its folder. This will
1. generate build files from .tt templates,
2. remove the TAfGT-specific projects from the solution (to avoid build problems for now),
3. restore the solution's NuGet packages,
4. copy the msdia140.dll DLLs from Visual Studio's DIA SDK folder into the according solution folders,
5. and build the CLR assembly for DIA SDK.
If you test build for Visual Studio 2017 and your installation is not either in C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise or C:\Program Files (x86)\Microsoft Visual Studio\2017\Community, the environment variable GTA_TESTS_VS2017 needs to be set to the correct path.