Document unexpected interaction with death test error code and gmock.main

If you have a death test that uses mock objects, it's very likely that those mock objects are not properly cleaned up before death. The gMock atexit leak detector will call `_exit(1)`, overriding your expected exit code.

PiperOrigin-RevId: 713722657
Change-Id: I92a326f3923efc9f0e235d825616f3094eca995c

1 files changed, 9 insertions, 3 deletions

diff --git a/docs/advanced.md b/docs/advanced.md
index 7e998cc..d4b44d5 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -416,7 +416,7 @@ corruption, security holes, or worse. Hence it is vitally important to test that
 such assertion statements work as expected.
 
 Since these precondition checks cause the processes to die, we call such tests
-_death tests_. More generally, any test that checks that a program terminates
+*death tests*. More generally, any test that checks that a program terminates
 (except by throwing an exception) in an expected fashion is also a death test.
 
 Note that if a piece of code throws an exception, we don't consider it "death"
@@ -462,6 +462,12 @@ verifies that:
     exit with exit code 0, and
 *   calling `KillProcess()` kills the process with signal `SIGKILL`.
 
+{: .callout .warning}
+Warning: If your death test contains mocks and is expecting a specific exit
+code, then you must allow the mock objects to be leaked via `Mock::AllowLeak`.
+This is because the mock leak detector will exit with its own error code if it
+detects a leak.
+
 The test function body may contain other assertions and statements as well, if
 necessary.
 
@@ -727,7 +733,7 @@ Some tips on using `SCOPED_TRACE`:
 ### Propagating Fatal Failures
 
 A common pitfall when using `ASSERT_*` and `FAIL*` is not understanding that
-when they fail they only abort the _current function_, not the entire test. For
+when they fail they only abort the *current function*, not the entire test. For
 example, the following test will segfault:
 
 ```c++
@@ -2382,7 +2388,7 @@ IMPORTANT: The exact format of the JSON document is subject to change.
 
 #### Detecting Test Premature Exit
 
-Google Test implements the _premature-exit-file_ protocol for test runners to
+Google Test implements the *premature-exit-file* protocol for test runners to
 catch any kind of unexpected exits of test programs. Upon start, Google Test
 creates the file which will be automatically deleted after all work has been
 finished. Then, the test runner can check if this file exists. In case the file