diff --git a/docs/source/conf.py b/docs/source/conf.py index bd5d0130b..496a97d84 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -219,4 +219,5 @@ intersphinx_mapping = { 'traits': ('http://docs.enthought.com/traits', None), 'pyface': ('http://docs.enthought.com/pyface', None), + "python": ("https://docs.python.org/3", None), } diff --git a/docs/source/enable/testing.rst b/docs/source/enable/testing.rst new file mode 100644 index 000000000..7b7406f72 --- /dev/null +++ b/docs/source/enable/testing.rst @@ -0,0 +1,54 @@ +========================= +Testing Enable Components +========================= + +In order to assist in the testing of enable :class:`~.Component` and +:class:`~.Interactor` objects, Enable provides the +:class:`~.EnableTestAssistant` class. This is a mixin class intended to work +along side :class:`python:unittest.TestCase`. Often times in order to +effectively test an enable component and its supported interactivity, one needs +to simulate user interactions such as moving/clicking/dragging the mouse, using +keys, etc. This involves manually creating the corresponding events with +appropriate state and dispatching them appropriately. This can be rather +tedious and :class:`~.EnableTestAssistant` provides a number of helper methods +to greatly simplify the process, making tests both faster/cleaner to write and +easier to read. Furthermore, in test scenarios it is ofen unnecessary to launch +the full application window and as such :class:`~.EnableTestAssistant` provides +a :meth:`~.create_mock_window` method for simply +mocking out the window itself. This allows for specifically testing the +component of interest alone, as is the goal in a unit test. Please see the api +docs (:class:`~.EnableTestAssistant`) for the full list of methods +available. + +Here is an example + +:: + + import unittest + from unittest import mock + + from enable.api import Component + from enable.testing import EnableTestAssistant + + class TestExample(unittest.TestCase): + def test_example(self): + test_assistant = EnableTestAssistant() + component = Component(bounds=[100, 200]) + + event = test_assistant.mouse_move(component, 10, 20) + self.assertEqual(event.x, 10) + self.assertEqual(event.y, 20) + self.assertFalse(event.alt_down) + self.assertFalse(event.control_down) + self.assertFalse(event.shift_down) + self.assertFalse(sevent.left_down) + self.assertEqual(event.window.get_pointer_position(), (10, 20)) + + component.normal_left_down = mock.Mock() + test_assistant.mouse_down(component, x=0, y=0) + component.normal_left_down.assert_called_once() + + event = test_assistant.mouse_move(component, 20, 30, left_down=True) + self.assertEqual(event.x, 20) + self.assertEqual(event.y, 30) + self.assertIs(event.left_down, True) diff --git a/docs/source/index.rst b/docs/source/index.rst index a6895bce4..b9193619b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,6 +31,7 @@ Enable enable/constraints_layout enable/traits enable/toolkit_selection + enable/testing credits