test_companion
==============

.. py:module:: test_companion

.. autoapi-nested-parse::

   Unit tests for MyPluginCompanion.

   This file is copied verbatim (with ``MyPluginCompanion`` replaced by your
   class name) when you create a new plugin with *New plugin from template…*.

   Quick-start
   -----------
   Run from the project root::

       pytest <your_plugin_dir>/tests/ -v

   Mocking strategy
   ----------------
   The companion needs a ``WolfMapViewer`` at construction time, but tests must
   work **without a display** (CI / headless servers).

   Two fixtures are provided:

   ``viewer``
       A :class:`~unittest.mock.MagicMock` that satisfies every attribute and
       method call.  We explicitly set ``xmin`` / ``xmax`` so that helper
       methods that compute sizes relative to the viewport return sensible
       values instead of zero.

   ``gl_mock``
       A fake ``OpenGL.GL`` module injected into ``sys.modules`` via
       ``monkeypatch``.  Without it, any call to ``_paint()`` would fail with an
       ``ImportError``.  The fixture exposes the mock so you can assert on
       specific OpenGL calls::

           c._paint(viewer)
           gl_mock.glVertex2f.assert_called()

   Key codes
   ---------
   Import ``KeyboardSnapshot`` and pass integer key codes.  Common values::

       _WXK_ESCAPE = 27
       _WXK_RETURN = 13









Module Contents
---------------

.. py:data:: _WXK_ESCAPE
   :value: 27


.. py:data:: _WXK_RETURN
   :value: 13


.. py:function:: viewer()

   Minimal WolfMapViewer stand-in (no wx, no display required).


.. py:function:: gl_mock(monkeypatch)

   Inject a headless OpenGL.GL module so paint methods do not crash.


.. py:function:: _ctx(x: float = 0.0, y: float = 0.0) -> wolfhece._viewer_plugin_handlers.MouseContext

   Build a right-click context at world coordinates (x, y).


.. py:function:: _kb(key_code: int, ctrl: bool = False) -> wolfhece._viewer_plugin_handlers.KeyboardSnapshot

   Build a keyboard event.


.. py:data:: _COMPANION_FILE

.. py:data:: _spec
   :value: None


.. py:data:: _mod
   :value: None


.. py:data:: MyPluginCompanion

.. py:class:: TestMyPluginCompanion

   Behaviour tests — pure Python, no wx, no display.


   .. py:method:: test_instantiation(viewer)

      The companion can be created without errors.



   .. py:method:: test_start_registers_action(viewer)


   .. py:method:: test_start_calls_viewer(viewer)


   .. py:method:: test_esc_stops_action(viewer)


   .. py:method:: test_unknown_key_returns_false(viewer)


   .. py:method:: test_paint_does_not_crash(viewer, gl_mock)