diff --git a/docs/faq.md b/docs/faq.md index 4e9583846..b2e24274b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,6 +1,6 @@ # GoogleTest FAQ -## Why should test suite names and test names not contain underscore? +## Why are there restrictions on underscores in test suite and test names? {: .callout .note} Note: GoogleTest reserves underscore (`_`) for special-purpose keywords, such as @@ -48,15 +48,25 @@ TEST(Time_Flies, Like_An_Arrow) { ... } Now, the two `TEST`s will both generate the same class (`Time_Flies_Like_An_Arrow_Test`). That's not good. -So for simplicity, we just ask the users to avoid `_` in `TestSuiteName` and -`TestName`. The rule is more constraining than necessary, but it's simple and -easy to remember. It also gives GoogleTest some wiggle room in case its -implementation needs to change in the future. +GoogleTest allows underscores (`_`) in test suite names and test names. + +However, certain underscore patterns are prohibited by the C++ standard: + +1. Any identifier that starts with an underscore followed by an upper-case + letter. +2. Any identifier that contains two consecutive underscores (`__`) anywhere in + its name. + +In addition, some combinations of underscores may cause internal name collisions +in the generated test class names. + + +If you violate the C++ reserved identifier rules or create a name collision, +there may not be immediate consequences, but your test may break with a new +compiler or a new version of GoogleTest. Therefore it is best to avoid leading +or trailing underscores and avoid double underscores in test suite and test +names. -If you violate the rule, there may not be immediate consequences, but your test -may (just may) break with a new compiler (or a new version of the compiler you -are using) or with a new version of GoogleTest. Therefore it's best to follow -the rule. ## Why does GoogleTest support `EXPECT_EQ(NULL, ptr)` and `ASSERT_EQ(NULL, ptr)` but not `EXPECT_NE(NULL, ptr)` and `ASSERT_NE(NULL, ptr)`? diff --git a/docs/primer.md b/docs/primer.md index 69d6c6ddc..b61e4416f 100644 --- a/docs/primer.md +++ b/docs/primer.md @@ -162,10 +162,17 @@ TEST(TestSuiteName, TestName) { `TEST()` arguments go from general to specific. The *first* argument is the name of the test suite, and the *second* argument is the test's name within the test -suite. Both names must be valid C++ identifiers, and they should not contain any -underscores (`_`). A test's *full name* consists of its containing test suite -and its individual name. Tests from different test suites can have the same -individual name. +suite. Both names must be valid C++ identifiers. + +Underscores (`_`) are allowed, but certain patterns are prohibited by the C++ +standard, including identifiers that begin with an underscore followed by an +upper-case letter or that contain consecutive underscores (`__`). In addition, +some underscore combinations may cause internal name collisions in generated +test class names. + +A test's *full name* consists of its containing test suite and its individual +name. Tests from different test suites can have the same individual name. + For example, let's take a simple integer function: diff --git a/docs/reference/testing.md b/docs/reference/testing.md index ea43721e5..8d41608ef 100644 --- a/docs/reference/testing.md +++ b/docs/reference/testing.md @@ -20,9 +20,17 @@ TEST(TestSuiteName, TestName) { Defines an individual test named *`TestName`* in the test suite *`TestSuiteName`*, consisting of the given statements. -Both arguments *`TestSuiteName`* and *`TestName`* must be valid C++ identifiers -and must not contain underscores (`_`). Tests in different test suites can have -the same individual name. +Both arguments *`TestSuiteName`* and *`TestName`* must be valid C++ identifiers. + +Underscores (`_`) are allowed, but identifiers must not: + +- start with an underscore followed by an upper-case letter, or +- contain two consecutive underscores (`__`). + +These restrictions follow the C++ standard rules for reserved identifiers. + +Tests in different test suites can have the same individual name. + The statements within the test body can be any code under test. [Assertions](assertions.md) used within the test body determine the outcome of @@ -40,8 +48,17 @@ Defines an individual test named *`TestName`* that uses the test fixture class *`TestFixtureName`*. The test suite name is *`TestFixtureName`*. Both arguments *`TestFixtureName`* and *`TestName`* must be valid C++ -identifiers and must not contain underscores (`_`). *`TestFixtureName`* must be -the name of a test fixture class—see +identifiers. + +Underscores (`_`) are allowed, but identifiers must not: + +- start with an underscore followed by an upper-case letter, or +- contain two consecutive underscores (`__`). + +These restrictions follow the C++ standard rules for reserved identifiers. + +*`TestFixtureName`* must be the name of a test fixture class—see + [Test Fixtures](../primer.md#same-data-multiple-tests). The statements within the test body can be any code under test. @@ -61,8 +78,17 @@ test fixture class *`TestFixtureName`*. The test suite name is *`TestFixtureName`*. Both arguments *`TestFixtureName`* and *`TestName`* must be valid C++ -identifiers and must not contain underscores (`_`). *`TestFixtureName`* must be -the name of a value-parameterized test fixture class—see +identifiers. + +Underscores (`_`) are allowed, but identifiers must not: + +- start with an underscore followed by an upper-case letter, or +- contain two consecutive underscores (`__`). + +These restrictions follow the C++ standard rules for reserved identifiers. + +*`TestFixtureName`* must be the name of a value-parameterized test fixture class—see + [Value-Parameterized Tests](../advanced.md#value-parameterized-tests). The statements within the test body can be any code under test. Within the test