Source code for jitx.test

"""
Unit test support
=================

The way the JITX python framework is designed makes testing a bit more
complicated than one would normally expect. The reason for this is how it
handles instantiation of class members. This package provides a base
:py:class:`TestCase` class that sets up the JITX framework for testing by
enabling objects to be instantiated within a test case. The main issue to note
here is that JITX structural classes must be defined outside the test class's
methods: defining one while instantiation is active raises TypeError.
"""

from dataclasses import dataclass
import unittest
from jitx._structural import instantiation
from jitx.context import Context




class TestCase(unittest.TestCase):
    """Base test case class with JITX context setup.

    This class sets up instantiation inside the test case, and registers a
    :py:class:`TestContext` which can be interrogated inside the design if
    desired. For the vast majority of cases, this class should be used as a
    base class instead of :py:class:`unittest.TestCase` when testing code that
    generates JITX design elements.

    The instantiation context is active from this class's ``setUpClass``
    through ``tearDownClass``, so ``setUp``, ``tearDown`` and the test methods
    all run inside it. Outside it, constructing a JITX structural object
    returns an uninstantiated placeholder, so reads of it do not return the
    declared values. Instantiation needs no JITX runtime. To construct an
    object that reads ``jitx.current.substrate`` outside a design, such as a
    land-pattern generator, instantiate a substrate in the test first, for
    example ``SampleSubstrate()``.
    """



    @classmethod
    def setUpClass(cls):
        cls.enterClassContext(instantiation.activate())
        TestContext(cls).set()
        super().setUpClass()






@dataclass(frozen=True)
class TestContext(Context):
    """Context for test execution. Will be set automatically if using
    :py:class:`jitx.test.TestCase` as a base class for your unit tests."""

    testClass: type[TestCase]
    """The test class being executed."""