"""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
    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