From a0ea592fdb7377a0f7223226b01cb8c9dd046a73 Mon Sep 17 00:00:00 2001
From: Kai Chappell <git@kschappell.com>
Date: Thu, 28 Aug 2025 21:57:03 +0000
Subject: [PATCH] Add test framework models

---
 src/py_dvt_ate/framework/__init__.py |   4 +
 src/py_dvt_ate/framework/context.py  | 111 +++++++++++++++++++++++++++
 2 files changed, 115 insertions(+)
 create mode 100644 src/py_dvt_ate/framework/context.py

diff --git a/src/py_dvt_ate/framework/__init__.py b/src/py_dvt_ate/framework/__init__.py
index 07cf042..4b1a8b9 100644
--- a/src/py_dvt_ate/framework/__init__.py
+++ b/src/py_dvt_ate/framework/__init__.py
@@ -3,3 +3,7 @@
 Provides test sequencing, measurement logging, limit checking,
 and runtime context management for DVT characterisation tests.
 """
+
+from py_dvt_ate.framework.context import ITest, TestContext
+
+__all__ = ["ITest", "TestContext"]
diff --git a/src/py_dvt_ate/framework/context.py b/src/py_dvt_ate/framework/context.py
new file mode 100644
index 0000000..3669ec7
--- /dev/null
+++ b/src/py_dvt_ate/framework/context.py
@@ -0,0 +1,111 @@
+"""Test framework context and interface definitions.
+
+This module defines the core abstractions for the test executive framework:
+- TestContext: Runtime context passed to tests during execution
+- ITest: Abstract base class that all DVT tests must implement
+
+The test framework orchestrates test execution, measurement logging, and
+result evaluation against limits.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from py_dvt_ate.data.models import TestStatus
+
+if TYPE_CHECKING:
+    # Avoid circular imports while maintaining type checking
+    from py_dvt_ate.framework.logger import ITestLogger  # type: ignore[import-not-found]
+    from py_dvt_ate.instruments.factory import InstrumentSet
+
+
+@dataclass
+class TestContext:
+    """Runtime context for test execution.
+
+    Provides access to instruments, logging, and configuration during test
+    execution. Passed to each test's execute() method.
+
+    Attributes:
+        run_id: Unique identifier for this test run (UUID).
+        instruments: Hardware abstraction layer providing access to all instruments.
+        logger: Test logger for recording measurements and events.
+        config: Test-specific configuration dictionary.
+    """
+
+    run_id: UUID
+    instruments: "InstrumentSet"
+    logger: "ITestLogger"
+    config: dict[str, Any]
+
+
+class ITest(ABC):
+    """Abstract base class for DVT test implementations.
+
+    All characterisation tests must inherit from this class and implement
+    the required properties and methods. The test runner uses these to
+    discover, describe, and execute tests.
+
+    Example:
+        class TempCoTest(ITest):
+            @property
+            def name(self) -> str:
+                return "tempco"
+
+            @property
+            def description(self) -> str:
+                return "Output voltage temperature coefficient"
+
+            def execute(self, context: TestContext) -> TestStatus:
+                # Test implementation...
+                return TestStatus.PASSED
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the unique test identifier.
+
+        Used for test discovery and selection. Should be lowercase,
+        alphanumeric with underscores (e.g., "tempco", "load_regulation").
+
+        Returns:
+            Unique test name string.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Return a human-readable test description.
+
+        Describes what the test measures or characterises. Displayed in
+        reports and user interfaces.
+
+        Returns:
+            Brief description of the test purpose.
+        """
+        pass
+
+    @abstractmethod
+    def execute(self, context: TestContext) -> TestStatus:
+        """Execute the test with the given context.
+
+        Contains the test logic: configure instruments, take measurements,
+        log results, and evaluate pass/fail. The test should use the
+        context.logger to record measurements and context.instruments to
+        control equipment.
+
+        Args:
+            context: Runtime context with instruments, logger, and config.
+
+        Returns:
+            Final test status (PASSED, FAILED, ERROR, etc.).
+
+        Raises:
+            Exception: If a critical error occurs during test execution.
+                      The test runner will catch this and mark the test as ERROR.
+        """
+        pass