Improve simulator timestamp in past errors, suggest reset, fix #490 (#…

…491)

doc/user_guide/_docs/A18-unit-testing.md

@@ -2,12 +2,22 @@
 title: "Unit Testing"
 permalink: /docs/unit-test/
 excerpt: "Unit Testing"
-last_modified_at: 2022-12-06
+last_modified_at: 2024-06-11
 toc: true
 ---
 
 Dart has a great unit testing package available on pub.dev: <https://pub.dev/packages/test>
 
-The ROHD package has a great set of examples of how to write unit tests for ROHD `Module`s in the test/ directory.
+The ROHD package has a great set of examples of how to write unit tests for ROHD `Module`s in the `test/` directory.
 
-Note that when unit testing with ROHD, it is important to reset the `Simulator` with `Simulator.reset()`.
+Note that when unit testing with ROHD, it is important to reset the `Simulator` with `Simulator.reset()` between tests.  For example, you could include something like the following so that the `Simulator` is always reset at the end of each of your tests:
+
+```dart
+void main() {
+  tearDown(() async {
+    await Simulator.reset();
+  });
+
+  test('my first test', () async {
+    ...
+```

lib/src/exceptions/exceptions.dart

@@ -10,4 +10,5 @@ export './name/name_exceptions.dart';
 export './sim_compare/sim_compare_exceptions.dart';
 export 'illegal_configuration_exception.dart';
 export 'rohd_exception.dart';
+export 'simulator_exception.dart';
 export 'unsupported_type_exception.dart';

lib/src/exceptions/simulator_exception.dart

@@ -0,0 +1,17 @@
+// Copyright (C) 2024 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// simulator_exception.dart
+// Definition for exception when an error occurs in the simulator.
+//
+// 2024 June 11
+// Author: Max Korbel <[email protected]>
+
+import 'package:rohd/rohd.dart';
+
+/// An [Exception] thrown when an error occurs in the simulator.
+class SimulatorException extends RohdException {
+  /// Constructs a new [Exception] for when an error occurs in the simulator
+  /// with [message] explaining why.
+  SimulatorException(super.message);
+}

lib/src/simulator.dart

@@ -191,8 +191,12 @@ abstract class Simulator {
   /// The [action], if it returns a [Future], will be `await`ed.
   static void registerAction(int timestamp, dynamic Function() action) {
     if (timestamp < _currentTimestamp) {
-      throw Exception('Cannot add timestamp "$timestamp" in the past.'
-          '  Current time is ${Simulator.time}');
+      throw SimulatorException('Cannot add timestamp "$timestamp" in the past.'
+          ' Current time is ${Simulator.time}.'
+          ' Did you mean to include a call to Simulator.reset()?'
+          ' If this is hit in a series of unit tests, see the user guide'
+          ' for tips:'
+          ' https://intel.github.io/rohd-website/docs/unit-test/');
     }
     if (!_pendingTimestamps.containsKey(timestamp)) {
       _pendingTimestamps[timestamp] = ListQueue();

test/simulator_test.dart

@@ -137,6 +137,16 @@ void main() {
     expect(injectedActionExecuted, isTrue);
   });
 
+  test('simulator exception when registering action in the past', () async {
+    Simulator.registerAction(100, () {
+      Simulator.registerAction(50, () {});
+    });
+
+    expect(() async {
+      await Simulator.run();
+    }, throwsA(isA<SimulatorException>()));
+  });
+
   group('Rohme compatibility tests', () {
     test('simulator supports delta cycles', () async {
       // ignore: omit_local_variable_types