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
  70
  71 ## Registering Test Manifests
  72
  73 To run Marionette Python tests locally via `mach` or as part of the `Mn` tests jobs
  74 in CI they need to be registered. This happens by adding a manifest file to the tree,
  75 which includes a reference to the test files and expectations for results.
  76
  77 Such a manifest file can look like the following and is stored with the extension `.toml`:
  78
  79 ```ini
  80 [DEFAULT]
  81
  82 ["test_expected_fail.py"]
  83 expected = "fail"
  84
  85 ["test_not_on_windows.py"]
  86 skip-if = ["os == 'win'"]
  87 ```
  88
  89 The registration of such a manifest file is done in two different ways:
  90
  91 1. To run the tests locally via `./mach test` or `./mach marionette-test` the
  92 created Marionette manifest file needs to be referenced in the folder's related
  93 `moz.build` file by adding it to the `MARIONETTE_MANIFESTS` variable like:
  94
  95     MARIONETTE_MANIFESTS += ["test/marionette/manifest.toml"]
  96
  97 2. To run the tests in CI the manifest file also needs to be included in the
  98 Marionette's own [master manifest file]. This ensures that the test packaging step
  99 will find the tests and include them as well in the test package.
 100
 101 [master manifest file]: https://searchfox.org/mozilla-central/source/testing/marionette/harness/marionette_harness/tests/unit-tests.toml