86 lines
5.6 KiB
Markdown
86 lines
5.6 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/StateMachine.Tests/StatesShould.cs
|
||
generated_at: "2026-04-16T03:49:48.727573+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "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.* |