test: Make time-system into a global singleton to simplify its use and plumbing, and avoid multi-time-system test confusion.

test/README.md

@@ -69,3 +69,31 @@ Examples:
 EXPECT_THAT(response->headers(), IsSubsetOfHeaders(allowed_headers));
 EXPECT_THAT(response->headers(), IsSupersetOfHeaders(required_headers));
 ```
+
+## Controlling time in tests
+
+In Envoy production code, time and timers are managed via
+[`Event::TimeSystem`](https://github.com/envoyproxy/envoy/blob/master/include/envoy/event/timer.h),
+which provides a mechanism for querying the time setting up time-based callbacks. Bypassing
+this abstraction in Envoy code is flagged as a format violation in CI.
+
+In tests we use a deriviation
+[`Event::TestTimeSystem`](test_common/test_time_system.h) which adds the ability
+to sleep or do a blocking timed wait on a condition variable. There are two
+implementations of the `Event::TestTimeSystem` interface:
+`Event::TestRealTimeSystem`, and `Event::SimulatedTimeSystem`. The latter is
+recommended for all new tests, as it helps avoid flaky tests on slow machines.
+
+Typically we do not want to have both real-time and simulated-time in the same
+test; that could lead to hard-to-reproduce results. Thus both implementations
+have a mechanism to enforce that only one of them can be instantiated at once.
+A runtime assertion occurs if a `Event::TestRealTimeSystem` and
+`Event::SimulatedTimeSystem` are instantiated at the same time. Once the
+time-systems go out of scope, usually at the end of of a test method, the slate
+is clean and a new test-method can use a different time system.
+
+There is also `Event::GlobalTimeSystem`, which can be instantiated in shared
+test infrastructure that wants to be agnostic to which `TimeSystem` is used in a
+test. When no `TimeSystem` is instantiated in a test, the `Event::GlobalTimeSystem`
+will lazy-initialize itself into a concrete `TimeSystem` -- currently this is
+`TestRealTimeSystem` but will be changed in the future to `SimulatedTimeSystem`.

tools/check_format.py

@@ -190,6 +190,8 @@ def whitelistedForProtobufDeps(file_path):
 # specific cases. They should be passed down from where they are instantied to where
 # they need to be used, e.g. through the ServerInstance, Dispatcher, or ClusterManager.
 def whitelistedForRealTime(file_path):
+  if file_path.endswith(".md"):
+    return True
   return file_path in REAL_TIME_WHITELIST