// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[cpp_testing]]
= Testing in C++ projects

Testing in the native ecosystem takes many forms.

There are different testing libraries and frameworks, as well as many different types of test.
All need to be part of the build, whether they are executed frequently or infrequently.
This chapter is dedicated to explaining how Gradle handles differing requirements between and within builds, with significant coverage of how it integrates with the executable-based testing frameworks, such as https://github.com/google/googletest[Google Test].

Testing C++ projects in Gradle is fairly limited when compared to <<java_testing.adoc#java_testing,Testing in Java & JVM projects>>. In this chapter, we explain the ways to control how tests are run (<<#sec:cpp_test_execution,Test execution>>).

But first, we look at the basics of native testing in Gradle.

[[sec:cpp_testing_basics]]
== The basics

All C++ testing revolves around a single task type: link:{groovyDslPath}/org.gradle.nativeplatform.test.tasks.RunTestExecutable.html[RunTestExecutable].
This runs a single test executable built with any testing framework and asserts the execution was successful using the exit code of the executable.
The test case results aren’t collected and no reports are generated.

In order to operate, the link:{groovyDslPath}/org.gradle.nativeplatform.test.tasks.RunTestExecutable.html[RunTestExecutable] task type requires just one piece of information:

 * Where to find the built test executable (property: link:{groovyDslPath}/org.gradle.nativeplatform.test.tasks.RunTestExecutable.html#org.gradle.nativeplatform.test.tasks.RunTestExecutable:executable[RunTestExecutable.getExecutable()])

When you’re using the <<cpp_unit_test_plugin.adoc#cpp_unit_test_plugin,{cpp} Unit Test Plugin>> you will automatically get the following:

 * A dedicated link:{groovyDslPath}/org.gradle.nativeplatform.test.cpp.CppTestSuite.html[unitTest] extension for configuring test component and its variants
 * A `run` task of type link:{groovyDslPath}/org.gradle.nativeplatform.test.tasks.RunTestExecutable.html[RunTestExecutable] that runs the test executable

The test plugins configure the required pieces of information appropriately.
In addition, they attach the `run` task to the `check` lifecycle task.
It also create the `testImplementation` dependency configuration.
Dependencies that are only needed for test compilation, linking and runtime may be added to this configuration.
The `unitTest` script block behave similarly to a `application` or `library` script block.

The link:{groovyDslPath}/org.gradle.nativeplatform.test.tasks.RunTestExecutable.html[RunTestExecutable] task has many configuration options.
We cover a number of them in the rest of the chapter.

[[sec:cpp_test_execution]]
== Test execution

Gradle executes tests in a separate (‘forked’) process.

You can control how the test process is launched via several properties on the link:{groovyDslPath}/org.gradle.nativeplatform.test.tasks.RunTestExecutable.html[RunTestExecutable] task, including the following:

`ignoreFailures` - default: false::
If this property is `true`, Gradle will continue with the project’s build once the tests have completed, even if some of them have failed.
Note that, by default, link:{groovyDslPath}/org.gradle.nativeplatform.test.tasks.RunTestExecutable.html[RunTestExecutable] task type always executes every test that it detects, irrespective of this setting.

See link:{groovyDslPath}/org.gradle.nativeplatform.test.tasks.RunTestExecutable.html[RunTestExecutable] for details on all the available configuration options.
