Implementation & Test Code

Code Organization

The TSIM implementation demonstrates traceability from requirements through architecture to code and tests.

examples/python_hello_world/
  ├── src/
  │   ├── __init__.py
  │   └── tsim.py              # Implementation with requirement IDs as docstring comments
  ├── tests/
  │   ├── __init__.py
  │   └── test_tsim.py         # Test cases linked to TEST_* requirements
  └── test_results.xml         # JUnit XML for sphinx-test-reports integration

Implementation Traceability

All code modules include requirement traceability in docstrings and comments. Click on requirement IDs below to navigate to their definitions:

Example: Sensor Driver Implementation

The SensorDriver class implements (FR) The module shall read ... (REQ_FUNC_001) (ADC conversion) as specified in (ARCH) The Sensor Driver sh... (ARCH_FUNC_001):

 1class SensorDriver:
 2    """
 3    ADC Sensor Input Driver
 4
 5    Traceability:
 6      - ARCH_FUNC_001: 100Hz sampling rate
 7      - REQ_FUNC_001: ADC to temperature conversion
 8      - ARCH_SIGNAL_001: 12-bit ADC input
 9      - ARCH_SIGNAL_002: 16-bit signed output
10    """
11
12    def read_adc(self, adc_counts: int) -> int:
13        """
14        Read ADC value and convert to temperature.
15
16        Traceability:
17            TEST_CONVERSION_001: Validates conversion
18            REQ_FUNC_001: Conversion requirement
19        """
20        # Linear interpolation: ADC counts → Celsius
21        celsius = (
22            self.ADC_MIN_CELSIUS +
23            (adc_counts - self.ADC_MIN_COUNTS) *
24            (self.ADC_MAX_CELSIUS - self.ADC_MIN_CELSIUS) /
25            (self.ADC_MAX_COUNTS - self.ADC_MIN_COUNTS)
26        )
27        # ...

Linked Requirements: (FR) The module shall read ... (REQ_FUNC_001), (ARCH) The Sensor Driver sh... (ARCH_FUNC_001), (ARCH) Raw Temperature Sign... (ARCH_SIGNAL_001), (ARCH) Temperature Reading ... (ARCH_SIGNAL_002)

State Machine Example

The StateMachine class implements (FR) The module shall trigg... (REQ_FUNC_003) and (FR) The module shall trigg... (REQ_FUNC_004) (threshold & hysteresis) as specified in (ARCH) Temperature monitori... (ARCH_DESIGN_001):

 1class StateMachine:
 2    """
 3    Temperature state machine with hysteresis.
 4
 5    Traceability:
 6      - ARCH_DESIGN_001: State machine architecture
 7      - REQ_SAFETY_002: Detect within 100ms
 8      - REQ_FUNC_003: Threshold detection
 9      - REQ_FUNC_004: Hysteresis recovery
10    """
11
12    def evaluate(self, temperature: int) -> TemperatureState:
13        """
14        Evaluate temperature with hysteresis.
15
16        Traceability:
17            TEST_THRESHOLD_001: Threshold at 100°C
18            TEST_HYSTERESIS_001: Hysteresis at 95°C
19        """
20        high_threshold = int(round(self.config.threshold_high_celsius * 10.0))
21        low_threshold = int(round(self.config.threshold_low_celsius * 10.0))
22
23        if self.state == TemperatureState.SAFE:
24            if temperature >= high_threshold:
25                self.state = TemperatureState.UNSAFE
26        elif self.state == TemperatureState.UNSAFE:
27            if temperature <= low_threshold:
28                self.state = TemperatureState.SAFE
29
30        return self.state

Test Suite Mapping

Need: (TEST) Test suite provides complete coverage of requirements. TEST_CODE_001 _images/arrow-right-circle.svg
status: active
tags: verification, testing, code

Test Coverage Matrix:

  • TestSensorDriver: Tests ARCH_FUNC_001, REQ_FUNC_001 - test_conversion_full_range → TEST_CONVERSION_001 - test_conversion_accuracy → TEST_CONVERSION_001

  • TestTemperatureFilter: Tests ARCH_FUNC_002, REQ_FUNC_002 - test_filter_noise_rejection → TEST_FILTER_001 - test_filter_stabilization → TEST_FILTER_001

  • TestStateMachine: Tests ARCH_DESIGN_001, REQ_FUNC_003/004 - test_threshold_detection → TEST_THRESHOLD_001 - test_hysteresis_deadband → TEST_HYSTERESIS_001 - test_state_output_bit → ARCH_SIGNAL_003

  • TestTSIMIntegration: Tests end-to-end ARCH_001 - test_end_to_end_latency → TEST_END_TO_END_001 - test_detection_within_100ms → TEST_END_TO_END_001 - test_safe_state_recovery → REQ_SAFETY_003 - test_error_recovery → TEST_ERROR_RECOVERY_001 - test_fail_safe_on_persistent_errors → TEST_FAIL_SAFE_001

Total: 13 test cases covering 20+ requirements

Test Execution & Reporting

 # Run tests with verbose output
cd examples/python_hello_world
 poetry run pytest tests/test_tsim.py -v

 # Generate JUnit XML for compliance reporting
 poetry run pytest tests/test_tsim.py --junit-xml=test_results.xml

 # Results can be imported by sphinx-test-reports for automated traceability

Test Results Integration

The generated test_results.xml can be integrated into Sphinx documentation via sphinx-test-reports:

conf.py configuration for test result integration
# Configure sphinx-test-reports
test_reports = {
    'junit': {
        'path': 'test_results.xml',
        'requirement_mapping': {
            'TEST_CONVERSION_001': 'REQ_FUNC_001',
            'TEST_FILTER_001': 'REQ_FUNC_002',
            'TEST_THRESHOLD_001': 'REQ_FUNC_003',
            # ... map all tests to requirements
        }
    }
}

Building the Full Chain

The complete traceability chain flows:

ISO 26262 Safety Goal (REQ_SAFETY_001)
         ↓
Safety Requirements (REQ_SAFETY_002/003)
         ↓
Functional Requirements (REQ_FUNC_001-004)
         ↓
Architectural Design (ARCH_FUNC_001-003, ARCH_DESIGN_001)
         ↓
Implementation Code (src/tsim.py)
         ↓
Unit Tests (tests/test_tsim.py)
         ↓
Test Results (test_results.xml)
         ↓
Documentation (index.rst, *.rst)
         ↓
Compliance Artifacts (HTML with traceability matrix)

Code Repository Structure

Need: (CODE) Complete example includes both documentation and implementation. CODE_REPO_001 _images/arrow-right-circle.svg
status: active
tags: repository, structure

File Listing:

  • 01_requirements.rst - Requirements specification

  • 02_architecture.rst - Architecture with diagrams

  • 03_verification.rst - Verification plan and traceability matrix

  • **04_implementation.rst** - This file (code examples and test mapping)

  • conf.py - Sphinx configuration

  • diagrams/ - PlantUML architecture diagrams

  • src/tsim.py - Implementation with traceability comments

  • tests/test_tsim.py - Comprehensive test suite

  • test_results.xml - JUnit test results

Extending the Example

To add more domains or features:

  1. Add new requirements to 01_requirements.rst

  2. Update architecture in 02_architecture.rst and diagrams/

  3. Extend implementation in src/tsim.py with domain-specific code

  4. Add tests in tests/test_tsim.py mapped to new test requirements

  5. Rebuild documentation: osqar build-docs --project examples/python_hello_world

  6. Run tests: pytest tests/ –junit-xml=test_results.xml

  7. Verify traceability: Check generated HTML matrix

This demonstrates how OSQAr enables complete compliance verification from high-level safety goals through low-level code and automated test reporting—all traceable in the generated documentation.