remote/doc/marionette/PythonTests.md

   1 # Mn Python tests
   2
   3 _Marionette_ is the codename of a [remote protocol] built in to
   4 Firefox as well as the name of a functional test framework for
   5 automating user interface tests.
   6
   7 The in-tree test framework supports tests written in Python, using
   8 Python’s [unittest] library.  Test cases are written as a subclass
   9 of `MarionetteTestCase`, with child tests belonging to instance
  10 methods that have a name starting with `test_`.
  11
  12 You can additionally define [`setUp`] and [`tearDown`] instance
  13 methods to execute code before and after child tests, and
  14 [`setUpClass`]/[`tearDownClass`] for the parent test.  When you use
  15 these, it is important to remember calling the `MarionetteTestCase`
  16 superclass’ own [`setUp`]/[`tearDown`] methods since they handle
  17 setup/cleanup of the session.
  18
  19 The test structure is illustrated here:
  20
  21 ```python
  22 from marionette_harness import MarionetteTestCase
  23
  24 class TestSomething(MarionetteTestCase):
  25     def setUp(self):
  26         # code to execute before any tests are run
  27         MarionetteTestCase.setUp(self)
  28
  29     def test_foo(self):
  30         # run test for 'foo'
  31
  32     def test_bar(self):
  33         # run test for 'bar'
  34
  35     def tearDown(self):
  36         # code to execute after all tests are run
  37         MarionetteTestCase.tearDown(self)
  38 ```
  39
  40 [remote protocol]: Protocol.md
  41 [unittest]: https://docs.python.org/3/library/unittest.html
  42 [`setUp`]: https://docs.python.org/3/library/unittest.html#unittest.TestCase.setUp
  43 [`setUpClass`]: https://docs.python.org/3/library/unittest.html#unittest.TestCase.setUpClass
  44 [`tearDown`]: https://docs.python.org/3/library/unittest.html#unittest.TestCase.tearDown
  45 [`tearDownClass`]: https://docs.python.org/3/library/unittest.html#unittest.TestCase.tearDownClass
  46
  47 ## Test assertions
  48
  49 Assertions are provided courtesy of [unittest].  For example:
  50
  51 ```python
  52 from marionette_harness import MarionetteTestCase
  53
  54 class TestSomething(MarionetteTestCase):
  55     def test_foo(self):
  56         self.assertEqual(9, 3 * 3, '3 x 3 should be 9')
  57         self.assertTrue(type(2) == int, '2 should be an integer')
  58 ```
  59
  60 ## The API
  61
  62 The full API documentation is found [here], but the key objects are:
  63
  64 * `MarionetteTestCase`: a subclass for `unittest.TestCase`
  65   used as a base class for all tests to run.
  66
  67 * {class}`Marionette <marionette_driver.marionette.Marionette>`: client that speaks to Firefox
  68
  69 [here]: /python/marionette_driver.rst