Skip to content

Commit 5c98531

Browse files
StoorxStoorx
committed
Add the documentation for CombineAs<R>() param generator
1 parent dc9ed8e commit 5c98531

File tree

4 files changed

+81
-19
lines changed

4 files changed

+81
-19
lines changed

‎docs/reference/testing.md

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -103,14 +103,15 @@ namespace:
103103
104104
<span id="param-generators"></span>
105105
106-
| Parameter Generator | Behavior |
107-
| ------------------- | ---------------------------------------------------- |
108-
| `Range(begin, end [, step])` | Yields values `{begin, begin+step, begin+step+step, ...}`. The values do not include `end`. `step` defaults to 1. |
109-
| `Values(v1, v2, ..., vN)` | Yields values `{v1, v2, ..., vN}`. |
110-
| `ValuesIn(container)` or `ValuesIn(begin,end)` | Yields values from a C-style array, an STL-style container, or an iterator range `[begin, end)`. |
111-
| `Bool()` | Yields sequence `{false, true}`. |
112-
| `Combine(g1, g2, ..., gN)` | Yields as `std::tuple` *n*-tuples all combinations (Cartesian product) of the values generated by the given *n* generators `g1`, `g2`, ..., `gN`. |
113-
| `ConvertGenerator<T>(g)` or `ConvertGenerator(g, func)` | Yields values generated by generator `g`, `static_cast` from `T`. (Note: `T` might not be what you expect. See [*Using ConvertGenerator*](#using-convertgenerator) below.) The second overload uses `func` to perform the conversion. |
106+
| Parameter Generator | Behavior |
107+
|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
108+
| `Range(begin, end [, step])` | Yields values `{begin, begin+step, begin+step+step, ...}`. The values do not include `end`. `step` defaults to 1. |
109+
| `Values(v1, v2, ..., vN)` | Yields values `{v1, v2, ..., vN}`. |
110+
| `ValuesIn(container)` or `ValuesIn(begin,end)` | Yields values from a C-style array, an STL-style container, or an iterator range `[begin, end)`. |
111+
| `Bool()` | Yields sequence `{false, true}`. |
112+
| `Combine(g1, g2, ..., gN)` | Yields as `std::tuple` *n*-tuples all combinations (Cartesian product) of the values generated by the given *n* generators `g1`, `g2`, ..., `gN`. |
113+
| `CombineAs<R>(g1, g2, ..., gN)` | Yields as `R` *n*-instances all combinations (Cartesian product) of the values generated by the given *n* generators `g1`, `g2`, ..., `gN`. |
114+
| `ConvertGenerator<T>(g)` or `ConvertGenerator(g, func)` | Yields values generated by generator `g`, `static_cast` from `T`. (Note: `T` might not be what you expect. See [*Using ConvertGenerator*](#using-convertgenerator) below.) The second overload uses `func` to perform the conversion. |
114115
115116
The optional last argument *`name_generator`* is a function or functor that
116117
generates custom test name suffixes based on the test parameters. The function
@@ -234,6 +235,24 @@ To overcome this problem you can specify the generated type explicitly:
234235
dangling reference because the type deduction strips off the reference and the
235236
`const`).
236237

238+
###### Using `CombineAs`
239+
240+
If you think the code above is too complicated, and you do not want to deal
241+
with tuples, you may want to use `CombineAs<R>()` which works like a combination
242+
of `Combine()` + `ConvertGenerator()` + tuple unpacking function.
243+
244+
```cpp
245+
// The fixture's parameter type.
246+
class MyParam {
247+
public:
248+
MyParam(int, bool);
249+
...
250+
};
251+
252+
INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,
253+
CombineAs<MyParam>(Values(1, 1.2), Bool()));
254+
```
255+
237256
### TYPED_TEST_SUITE {#TYPED_TEST_SUITE}
238257
239258
`TYPED_TEST_SUITE(`*`TestFixtureName`*`,`*`Types`*`)`

‎docs/samples.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ variety of googletest features.
1515
derived fixtures.
1616
* Sample #6 demonstrates type-parameterized tests.
1717
* Sample #7 teaches the basics of value-parameterized tests.
18-
* Sample #8 shows using `Combine()` in value-parameterized tests.
18+
* Sample #8 shows using `Combine()` and `CombineAs<R>()` in value-parameterized tests.
1919
* Sample #9 shows use of the listener API to modify Google Test's console
2020
output and the use of its reflection API to inspect test results.
2121
* Sample #10 shows use of the listener API to implement a primitive memory

‎googletest/include/gtest/gtest.h

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -61,15 +61,15 @@
6161
#include <vector>
6262

6363
#include "gtest/gtest-assertion-result.h" // IWYU pragma: export
64-
#include "gtest/gtest-death-test.h" // IWYU pragma: export
65-
#include "gtest/gtest-matchers.h" // IWYU pragma: export
66-
#include "gtest/gtest-message.h" // IWYU pragma: export
67-
#include "gtest/gtest-param-test.h" // IWYU pragma: export
68-
#include "gtest/gtest-printers.h" // IWYU pragma: export
69-
#include "gtest/gtest-test-part.h" // IWYU pragma: export
70-
#include "gtest/gtest-typed-test.h" // IWYU pragma: export
71-
#include "gtest/gtest_pred_impl.h" // IWYU pragma: export
72-
#include "gtest/gtest_prod.h" // IWYU pragma: export
64+
#include "gtest/gtest-death-test.h" // IWYU pragma: export
65+
#include "gtest/gtest-matchers.h" // IWYU pragma: export
66+
#include "gtest/gtest-message.h" // IWYU pragma: export
67+
#include "gtest/gtest-param-test.h" // IWYU pragma: export
68+
#include "gtest/gtest-printers.h" // IWYU pragma: export
69+
#include "gtest/gtest-test-part.h" // IWYU pragma: export
70+
#include "gtest/gtest-typed-test.h" // IWYU pragma: export
71+
#include "gtest/gtest_pred_impl.h" // IWYU pragma: export
72+
#include "gtest/gtest_prod.h" // IWYU pragma: export
7373
#include "gtest/internal/gtest-internal.h"
7474
#include "gtest/internal/gtest-string.h"
7575

@@ -1661,7 +1661,8 @@ class GTEST_API_ AssertHelper {
16611661
// the GetParam() method.
16621662
//
16631663
// Use it with one of the parameter generator defining functions, like Range(),
1664-
// Values(), ValuesIn(), Bool(), Combine(), and ConvertGenerator<T>().
1664+
// Values(), ValuesIn(), Bool(), Combine(), CombineAs<R>(), and
1665+
// ConvertGenerator<T>().
16651666
//
16661667
// class FooTest : public ::testing::TestWithParam<int> {
16671668
// protected:

‎googletest/samples/sample8_unittest.cc

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ class HybridPrimeTable : public PrimeTable {
8181

8282
using ::testing::Bool;
8383
using ::testing::Combine;
84+
using ::testing::CombineAs;
8485
using ::testing::TestWithParam;
8586
using ::testing::Values;
8687

@@ -151,4 +152,45 @@ TEST_P(PrimeTableTest, CanGetNextPrime) {
151152
INSTANTIATE_TEST_SUITE_P(MeaningfulTestParameters, PrimeTableTest,
152153
Combine(Bool(), Values(1, 10)));
153154

155+
// But now you look at the PrimeTableTest and you think dealing with std::tuple
156+
// requires some boilerplate to unwrap it. You can use combined parameters of
157+
// custom types easily with help of CombineAs<R>().
158+
struct WellTypedPrimeTableTestParams {
159+
bool force_on_the_fly;
160+
int max_precalculated;
161+
};
162+
163+
class WellTypedPrimeTableTest
164+
: public TestWithParam<WellTypedPrimeTableTestParams> {
165+
protected:
166+
void SetUp() override {
167+
// It is possible to avoid destructuring of the std::tuple if we use struct
168+
// as the test parameter type.
169+
table_ = new HybridPrimeTable(GetParam().force_on_the_fly,
170+
GetParam().max_precalculated);
171+
}
172+
void TearDown() override {
173+
delete table_;
174+
table_ = nullptr;
175+
}
176+
HybridPrimeTable* table_ = nullptr;
177+
};
178+
179+
// The tests are made the same way as above
180+
TEST_P(WellTypedPrimeTableTest, CanGetNextPrime) {
181+
EXPECT_EQ(2, table_->GetNextPrime(0));
182+
EXPECT_EQ(3, table_->GetNextPrime(2));
183+
EXPECT_EQ(5, table_->GetNextPrime(3));
184+
EXPECT_EQ(7, table_->GetNextPrime(5));
185+
EXPECT_EQ(11, table_->GetNextPrime(7));
186+
EXPECT_EQ(131, table_->GetNextPrime(128));
187+
}
188+
189+
// Here we instantiate our tests with combined parameters and straightforward
190+
// typing. CombineAs<R>() allows you to generate all possible combinations of
191+
// values the same way as Combine() does, but also converts them to the desired
192+
// type.
193+
INSTANTIATE_TEST_SUITE_P(MeaningfulTestParameters, WellTypedPrimeTableTest,
194+
CombineAs<WellTypedPrimeTableTestParams>(Bool(), Values(1, 10)));
195+
154196
} // namespace

0 commit comments

Comments
 (0)