108 lines
6.4 KiB
Markdown
108 lines
6.4 KiB
Markdown
---
|
|
source_files:
|
|
- DataPRO/SensorDB.Test/SensorDataShould.cs
|
|
- DataPRO/SensorDB.Test/IsoCodeShould.cs
|
|
- DataPRO/SensorDB.Test/SensorCalibrationShould.cs
|
|
generated_at: "2026-04-16T03:45:54.975833+00:00"
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|
schema_version: 1
|
|
sha256: "b51d16198cb266e3"
|
|
---
|
|
|
|
# SensorDB.Test
|
|
|
|
## Documentation: SensorDB Module (Test-Focused)
|
|
|
|
This document describes the **behavioral contract** inferred from unit tests in the `SensorDB.Tests` project. It reflects expected public behaviors of core types in the `DTS.SensorDB` namespace, as verified by unit tests. **Note**: These are *test-driven specifications*, not implementation files; they define *what* the code must do, not *how*.
|
|
|
|
---
|
|
|
|
### 1. **Purpose**
|
|
|
|
This module provides core data structures and validation logic for sensor calibration metadata and related utilities, primarily used in data acquisition and processing pipelines. It includes types for representing calibration records (`SensorCalibration`, `IsoCode`, `InitialOffset`), supporting operations like compatibility checks (e.g., IEPE sensor compatibility), string formatting, and comparison. The tests validate behavior for edge cases (e.g., null/empty inputs, missing calibration data) to ensure robustness in downstream systems.
|
|
|
|
---
|
|
|
|
### 2. **Public Interface**
|
|
|
|
#### `SensorData.GetInitialEUValue(ISensorCalibration calibration, ExcitationVoltageOptions.ExcitationVoltageOption excitation, InitialOffset initialOffset)`
|
|
|
|
- **Behavior**: Retrieves the initial engineering unit (EU) value for a given excitation voltage, based on calibration data and an `InitialOffset` configuration.
|
|
- **Exceptions**: Throws `NullReferenceException` with message `"No calibration record found for {ExcitationVoltage}"` if no `ICalibrationRecord` exists in `calibration.Records` matching the specified `excitation`.
|
|
- **Note**: The test uses `ExcitationVoltageOption.Volt3` while the mock only provides `Volt2`, triggering the exception.
|
|
|
|
#### `IsoCode.TestObject { get; set; }`
|
|
|
|
- **Type**: `string`
|
|
- **Behavior**:
|
|
- When set to `null`, the property value becomes `"?"`.
|
|
- When set to `""` (empty string), the property value becomes `"?"`.
|
|
- Otherwise, it stores and returns the assigned string value unchanged.
|
|
|
|
#### `IsoCode.StringRepresentation { get; }`
|
|
|
|
- **Type**: `string`
|
|
- **Behavior**:
|
|
- Returns the raw `TestObject` value *if* it is non-null and non-empty.
|
|
- If `TestObject` ends before 16 characters, appends enough `"?"` characters to reach a total length of 16.
|
|
- Example: `"??RIBS0200HF"` (12 chars) → `"??RIBS0200HF????"` (16 chars).
|
|
- If `TestObject` is `null` or empty, `StringRepresentation` returns `"?"` (inferred from `TestObject` behavior and test expectations).
|
|
|
|
#### `SensorCalibration.IsCompatibleWithIEPE()`
|
|
|
|
- **Return Type**: `bool`
|
|
- **Behavior**:
|
|
- Returns `false` if `IsProportional` is `true`.
|
|
- Returns `false` if `NonLinear` is `true`.
|
|
- Returns `true` only if both `IsProportional == false` and `NonLinear == false`.
|
|
|
|
#### `SensorCalibration.ToNonLinearDisplayString(string value, bool force)`
|
|
|
|
- **Return Type**: `string`
|
|
- **Behavior**:
|
|
- Returns `""` (empty string) if `NonLinear` is `false`.
|
|
- Returns `""` if `value` is `null` (regardless of `NonLinear`).
|
|
- *(No tests confirm behavior when `NonLinear == true` and `value != null`; behavior unknown.)*
|
|
|
|
#### `SensorCalibration.CompareTo(object obj)`
|
|
|
|
- **Return Type**: `int` (implements `IComparable`)
|
|
- **Behavior**:
|
|
- Returns `1` if `obj` is `null`.
|
|
- Returns `0` if `obj` is a `SensorCalibration` with the same `CalibrationDate`.
|
|
- Returns a non-zero value (negative or positive) if `CalibrationDate` differs (exact ordering not specified beyond non-zero).
|
|
- *Note: Only `CalibrationDate` is used for comparison in the tests.*
|
|
|
|
---
|
|
|
|
### 3. **Invariants**
|
|
|
|
- `IsoCode.StringRepresentation` is always exactly 16 characters long *if* `TestObject` is non-null and non-empty, padded with `"?"` to the right.
|
|
- `IsoCode.TestObject` is never `null` or empty in its *stored* value; both are normalized to `"?"`.
|
|
- `SensorCalibration.IsCompatibleWithIEPE()` is `true` **iff** both `NonLinear == false` and `IsProportional == false`.
|
|
- `SensorData.GetInitialEUValue(...)` requires a matching `ICalibrationRecord` for the given `excitation`; otherwise, it fails with a `NullReferenceException` (not `ArgumentException` or `KeyNotFoundException`).
|
|
- `SensorCalibration.CompareTo(null)` always returns `1`, indicating `this` instance is "greater than" `null`.
|
|
|
|
---
|
|
|
|
### 4. **Dependencies**
|
|
|
|
- **Internal Dependencies** (inferred from test imports):
|
|
- `DTS.SensorDB` namespace (contains `SensorData`, `SensorCalibration`, `IsoCode`, `InitialOffset`, `InitialOffsetTypes`, `ExcitationVoltageOptions`, `ISensorCalibration`, `ICalibrationRecord`).
|
|
- `DTS.Common.Interface.Sensors`, `DTS.Common.Enums`, `DTS.Common.Classes.Sensors`, `DTS.Common.Enums.Sensors` (for sensor-related types).
|
|
- **Test Frameworks**:
|
|
- `NUnit` (test runner/assertions).
|
|
- `NSubstitute` (mocking framework for interfaces like `ISensorCalibration`, `ICalibrationRecord`).
|
|
- **No external runtime dependencies** beyond .NET standard libraries and the above internal modules.
|
|
|
|
---
|
|
|
|
### 5. **Gotchas**
|
|
|
|
- **`NullReferenceException` for missing calibration data**: `SensorData.GetInitialEUValue` throws `NullReferenceException` (not a more semantically appropriate exception like `KeyNotFoundException` or `ArgumentException`) when no calibration record matches the requested excitation. This is a potential anti-pattern and may mislead developers expecting a domain-specific exception.
|
|
- **`IsoCode` padding behavior is implicit**: The 16-character padding rule is only verified for the `StringRepresentation` property, but not explicitly documented in the source. Developers must infer that padding is applied *only* when `TestObject` is non-null/non-empty.
|
|
- **`ToNonLinearDisplayString` behavior is underspecified**: Tests cover only the `NonLinear == false` or `value == null` cases. Behavior when `NonLinear == true` and `value != null` is unknown.
|
|
- **`CompareTo` uses only `CalibrationDate`**: Despite `SensorCalibration` likely having other fields (e.g., serial number, model), tests confirm comparison is based solely on `CalibrationDate`. This may cause unexpected ordering if other fields are expected to participate.
|
|
- **No tests for `SensorCalibration` equality (`Equals`/`GetHashCode`)**: While `CompareTo` is tested, equality semantics are not verified — may differ from date-only comparison.
|
|
|
|
None identified beyond the above. |