--- a/testing/marionette/doc/Intro.md
+++ b/testing/marionette/doc/Intro.md
@@ -51,27 +51,27 @@ outside component (the Marionette client
 The Marionette server ships with Firefox, and to use it you will
 need to download a Marionette client or use the in-tree client.
 
   * [Download and setup the Python client for Marionette][2]
   * [Run Tests with Python][3] – How to run tests using the
     Python client
   * You might want to experiment with [using Marionette interactively
     at a Python command prompt][3]
-  * Start [writing and running][4] tests with supported test frameworks!
+  * Start [writing and running][4] tests
   * Tips on [debugging][5] Marionette code
   * [Get a Build][6] – Instructions on how to get a Marionette-enabled
     build of Firefox
   * [Download and setup the Marionette JS client][7]
   * [Protocol definition][8]
 
 [1] https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver
 [2] http://marionette-client.readthedocs.io/en/latest/
 [3] http://marionette-client.readthedocs.io/en/latest/interactive.html
-[4] https://developer.mozilla.org/en/Marionette/Tests
+[4] ./PythonTests.md
 [5] ./Debugging.md
 [6] https://developer.mozilla.org/en-US/docs/Marionette/Builds
 [7] https://github.com/mozilla-b2g/marionette_js_client
 [8] https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/Protocol
 
 
 Bugs
 ====

new file mode 100644
--- /dev/null
+++ b/testing/marionette/doc/PythonTests.md
@@ -0,0 +1,73 @@
+Mn Python tests
+===============
+
+_Marionette_ is the codename of a [remote protocol] built in to
+Firefox as well as the name of a functional test framework for
+automating user interface tests.
+
+The in-tree test framework supports tests written in Python, using
+Python’s [unittest] library.  Test cases are written as a subclass
+of [`MarionetteTestCase`], with child tests belonging to instance
+methods that have a name starting with `test_`.
+
+You can additionally define [`setUp`] and [`tearDown`] instance
+methods to execute code before and after child tests, and
+[`setUpClass`]/[`tearDownClass`] for the parent test.  When you use
+these, it is important to remember calling the [`MarionetteTestCase`]
+superclass’ own `setUp`/`tearDown` methods since they handle
+setup/cleanup of the session.
+
+The test structure is illustrated here:
+
+	from marionette_test import MarionetteTestCase
+
+	class TestSomething(MarionetteTestCase):
+	    def setUp(self):
+	        # code to execute before any tests are run
+	        MarionetteTestCase.setUp(self)
+
+	    def test_foo(self):
+	        # run test for 'foo'
+
+	    def test_bar(self):
+	        # run test for 'bar'
+
+	    def tearDown(self):
+	        # code to execute after all tests are run
+	        MarionetteTestCase.tearDown(self)
+
+[remote protocol]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/Protocol
+[unittest]: https://docs.python.org/2.7/library/unittest.html
+[`MarionetteTestCase`]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/MarionetteTestCase
+[`setUp`]: https://docs.python.org/2.7/library/unittest.html#unittest.TestCase.setUp
+[`setUpClass`]: https://docs.python.org/2.7/library/unittest.html#unittest.TestCase.setUpClass
+[`tearDown`]: https://docs.python.org/2.7/library/unittest.html#unittest.TestCase.tearDown
+[`tearDownClass`]: https://docs.python.org/2.7/library/unittest.html#unittest.TestCase.tearDownClass
+
+
+Test assertions
+---------------
+
+Assertions are provided courtesy of [unittest].  For example:
+
+	from marionette_test import MarionetteTestCase
+
+	class TestSomething(MarionetteTestCase):
+	    def test_foo(self):
+	        self.assertEqual(9, 3 * 3, '3 x 3 should be 9')
+	        self.assertTrue(type(2) == int, '2 should be an integer')
+
+
+The API
+-------
+
+The full API documentation is found at
+http://marionette-client.readthedocs.io/en/master/, but the key
+objects are:
+
+  * [`MarionetteTestCase`]: a subclass for `unittest.TestCase`
+    used as a base class for all tests to run.
+
+  * [`Marionette`]: client that speaks to Firefox.
+
+[`Marionette`]: http://marionette-client.readthedocs.io/en/master/reference.html#marionette