google / google/googletest

[FR]: Please improve documentation regarding "test crashes"

Open
#4,790 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
C++
Stars
39.5k
Forks
10.9k
Avg merge
6d 13h
Merged PRs (30d)
1

Description

### Does the feature exist in the most recent commit?

No.

### Why do we need this feature?

Documentation should be clear.

### Describe the proposal.

In "Basic Concepts" in [Primer](https://google.github.io/googletest/primer.html#basic-concepts) it says:

`If a test crashes or has a failed assertion, then it fails`

What is a **test crash** ?

My guess is that the word "crash" was used incorrectly here... Maybe you mean "uncaught exception or structured exception is thrown from the test"? Or are there any other kinds of "crashes" that are handled by GoogleTest?

---

For example, if I do **division by 0**, then on Linux the **test exec will crash** with `Floating point exception (core dumped)` and exit code 136, no other tests will be executed. (On Windows, a structured exception will be thrown and handled by GoogleTest).

Also, in "Detecting Test Premature Exit" in [Advanced Topics](https://google.github.io/googletest/advanced.html#detecting-test-premature-exit) it says:

`Google Test implements the premature-exit-file protocol for test runners to catch any kind of unexpected exits of test programs`

But even if I set the TEST_PREMATURE_EXIT_FILE, the file is created, but the test exec behavior does not change.

I understand there are [Death Tests](https://google.github.io/googletest/advanced.html#death-tests) and I assume they would detect/catch such crash (haven't checked).

---

Repro:

```
#include "gtest/gtest.h"

int x = 0;

TEST(CrashTest, Test1) {
ASSERT_FALSE(10 / x > 0);
}

TEST(CrashTest, Test2) {
ASSERT_TRUE(10 > 0);
}
```

### Is the feature specific to an operating system, compiler, or build system version?

No.

Contributor guide

Open the contributing guide

Research direction

Start with the linked Primer “Basic Concepts” and Advanced Topics “Detecting Test Premature Exit” sections, then run the provided CrashTest reproduction on the relevant platform. Compare the documented behavior with the observed division-by-zero and premature-exit-file behavior. Done means the documentation clearly defines “test crash” and accurately explains the protocol’s behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation, testing
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.