From 4d7bd304e795b3b55059ae9faf81de0d8323e526 Mon Sep 17 00:00:00 2001
From: Chris Hamons <chris.hamons@xamarin.com>
Date: Wed, 26 Sep 2018 10:24:49 -0500
Subject: [PATCH] Update tests/README to document XM_TEST_NAME (#4880)

- https://github.com/xamarin/xamarin-macios/issues/3609
---
 tests/README.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/tests/README.md b/tests/README.md
index 3d92d9ec6e..2acb4a236c 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -72,7 +72,20 @@ Con
 
 * The data might not represent the truth (errors, false positives...)
 
+### Xamarin.Mac
 
+Many tests when run for macOS use a integration [hack](https://github.com/xamarin/xamarin-macios/blob/master/tests/common/mac/MacTestMain.cs) which helps handle a number of issues:
+
+- Allowing command line arguments to tests while excluding "psn" arguments passed in while debugging with Visual Studio for Mac
+- Optionally integrating with the macOS message loop for tests that require it (anything that uses most Cocoa primitives).
+- Invoking `_exit` to work around a number of post-test hangs. See the [bug](https://bugzilla.xamarin.com/show_bug.cgi?id=52604) for details.
+- Add a number of "default" excludes for mono BCL tests
+
+One very useful "hack" this support adds is the ability to run a single test from the command line via the `XM_TEST_NAME` environmental variable. For example
+
+```
+XM_TEST_NAME=MonoTouchFixtures.Security.KeyTest.CreateRandomKeyWithParametersTests make run-mac-unified-xammac_tests
+```
 
 # Test Suites