DP44/enriched-qwen3-coder-next/DataPRO/StateMachine.Tests.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/StateMachine.Tests/StatesShould.cs	2026-04-16T03:49:48.727573+00:00	Qwen/Qwen3-Coder-Next-FP8	1	ae00661176117a50

StateMachine.Tests

Documentation Page: States Class (StateMachine Module)

---

1. Purpose

The States class serves as a singleton registry and factory for all known DAS (Data Acquisition System) state objects, ensuring consistent access to state instances and enabling centralized configuration of shared dependencies (e.g., IDASFactory). It abstracts the instantiation and management of state objects—each corresponding to a value in the State enum—so that other parts of the system can retrieve fully initialized, type-safe state representations without duplicating construction logic or state-specific dependencies.

---

2. Public Interface

public static States Instance { get; }

• Type: Static read-only property
• Behavior: Returns the singleton instance of States. Guaranteed to be non-null and identical across all calls (verified by Instance_ShouldBeSame test).

public static void SetDASFactory(IDASFactory factory)

• Behavior: Assigns the provided IDASFactory instance to all state objects managed by States. After calling this, every state retrieved via GetIDASState(...) will have its DASFactory property set to the provided factory.
• Note: Must be called before states are accessed (or at least before GetIDASState is invoked), as state objects are lazily initialized and only receive the factory upon first access (inferred from test SetDASFactory_ShouldSetToAnInstanceOfDASFactory).

public IDASState GetIDASState(State state)

• Parameters:
  • state: A value from the State enum (e.g., State.Arm, State.Realtime).
• Returns: An IDASState instance corresponding to the requested State.
• Behavior:
  • Returns a state object whose State property matches the input state.
  • Throws InvalidOperationException with message "Undefined State" if passed a State value not defined in the State enum (e.g., (State)45).
  • The returned IDASState will have its DASFactory property set if SetDASFactory was previously called.

public DASState Arm { get; }

public DASState Arming { get; }

public DASState Configure { get; }

public DASState ConfigureStart { get; }

public DASState Diagnose { get; }

public DASState Download { get; }

public DASState HardwareDiscovery { get; }

public DASState HardwareDiscoveryStart { get; }

public DASState Prepare { get; }

public DASState Realtime { get; }

public DASState RealtimeStart { get; }

• Type: Read-only properties (return type inferred as DASState, a concrete implementation of IDASState).
• Behavior: Each property exposes a pre-instantiated state object corresponding to its name (e.g., Arm returns the DASState for State.Arm). All are non-null and initialized with their respective State enum value.

---

3. Invariants

• Singleton Consistency: States.Instance always returns the same object reference.
• State Completeness: For every defined State enum value, States.Instance.GetIDASState(state) returns a valid IDASState with State == state.
• Factory Propagation: After SetDASFactory(factory) is called, all states returned by GetIDASState(...) (and exposed via named properties like Arm, Realtime, etc.) must have DASFactory == factory.
• Enum Validity Enforcement: GetIDASState(...) rejects any State value not present in the State enum via InvalidOperationException.
• Non-null States: All state properties (Arm, Arming, etc.) and results from GetIDASState(...) are non-null.

---

4. Dependencies

Depends on

• DTS.DASLib.Service.StateMachine namespace (contains States, IDASState, DASState, State enum).
• DTS.Common.Interface.DASFactory namespace (contains IDASFactory).
• NUnit.Framework (for test assertions).
• NSubstitute (for mocking IDASFactory in tests).

Depended on by

• StateMachine.Tests (this file), which validates States behavior.
• Inferred: Other modules in DTS.DASLib.Service.StateMachine (and possibly higher-level services) rely on States to obtain state objects.

---

5. Gotchas

• Factory Initialization Timing: SetDASFactory must be called before accessing state objects via GetIDASState(...) or named properties (e.g., States.Instance.Arm), otherwise states may be initialized with a null DASFactory.
• Lazy Initialization: State objects are not pre-instantiated at Instance construction; they are created on first access (e.g., when Arm or GetIDASState(State.Arm) is called), and only then receive the factory if SetDASFactory has been called.
• No Explicit State Transition Logic: This module only manages state instances and their shared dependencies. It does not define state transitions, guards, or event handling (those are likely elsewhere in the StateMachine namespace).
• Test Interdependence: The SetDASFactory_ShouldSetToAnInstanceOfDASFactory test assumes GetIDASState works correctly (see inline comment). If GetIDASState fails, this test’s failure mode is ambiguous.
• Undefined State Handling: Passing an invalid State enum value (e.g., via cast (State)45) throws InvalidOperationException—not ArgumentOutOfRangeException—despite the input being an enum value.

None identified beyond the above.