Validator.get_config helper

docs/pages/architecture.md

@@ -68,9 +68,20 @@ Before running tests, you need to setup a configuration for the equipment you're
 The configuration is stored as a YAML file and loaded into a Ruby object. A test can access the configurations using `Validator.config`. For example, a test might access a specific watchdog timeout using:
 
 ```ruby
-timeout = Validator.config['timeouts']['watchdog']
+timeout = Validator.config['timeouts','watchdog']
 ```
 
+The helper `Validator.get_config` can be used to fetch config values, while providing a default value and stopping if the config is missing. You pass an array of keys, which will be used to fetch the config, and optionally a default value:
+
+```ruby
+timeout = Validator.get_config('timeouts','watchdog', default: 5)
+```
+
+If the config value is not found, the default will be used if provided, but a warning will be printed.
+If the config is not found, and not default is provided, the test will be aborted, showing an error.
+
+In general, default values are not encouraged, as different types of equipment often require different configurations. For this reason, it's usually better not to provide a default value, and instead require that the config is present.
+
 ### Logging
 During testing, a log is generated by RSpec. It's often useful to print to the log, for example to print information about what steps are being performed by the test. If a test fails, this will make it easier to understand the log file.
 
@@ -102,8 +113,8 @@ RSpec.describe "Traffic Light Controller" do
         prepare task, site
         with_clock_set CLOCK do
           Validator.log "Checking watchdog timestamp", level: :test
-          response = site.collect type: "Watchdog", num: 1, timeout: Validator.config['timeouts']['watchdog']
-          max_diff = Validator.config['timeouts']['command_response'] + Validator.config['timeouts']['status_response']
+          response = site.collect type: "Watchdog", num: 1, timeout: Validator.get_config('timeouts','watchdog')
+          max_diff = Validator.get_config('timeouts','command_response') + Validator.get_config('timeouts','status_response')
           diff = Time.parse(response.attributes['wTs']) - CLOCK
           diff = diff.round
           expect(diff.abs).to be <= max_diff,

docs/pages/configuring.md

@@ -58,6 +58,7 @@ sxl: tlc                # sxl of the connecting site, options are 'core' or 'tlc
 intervals:
   timer: 1              # main timer interval (resolution), in seconds
   watchdog: 1           # how often to send watchdog messages, in seconds
+
 timeouts:
   watchdog: 2           # max time bewteen incoming watchdogs, in seconds
   acknowledgement: 2    # max time until acknowledgement is received, in seconds
@@ -73,6 +74,7 @@ timeouts:
   shutdown: 1           # max time until site shuts down for a restart, in seconds
   startup_sequence: 5     # max time until startup sequence completes
   functional_position: 2  # max time until requested functional position is reached
+  yellow_flash: 2         # max time until yellow flash is activated
 components:             # list of rsmp components, organized by type and name, in seconds
   main:                 # type
     TC:                 # name. note that this is an (empty) options hash
@@ -89,8 +91,8 @@ items:                  # other configurations that should be tested
   force_input: 5              # what input to force when testing input forcing
 startup_sequence: 'efg' # expected startup sequence
 restrict_testing:       # restrict what tests are run, default is to run all
-  core_version: 3.1.5   # skip unless relevant for core 3.1.5
-  sxl_version: 1.0.13   # skip unless relevant for sxl 1.0.13
+  core_version: 3.2.1   # skip unless relevant for core 3.2.1
+  sxl_version: 1.1      # skip unless relevant for sxl 1.1
 secrets:                # place secrets or in a separate file, see below
   security_codes:       # RSMP security codes. there are no defaults for these
     1: '1111'           # level 1
@@ -119,7 +121,7 @@ supervisors:          # what supervisor the local site should connect to
   - ip: 127.0.0.1       # ip
     port: 13111         # port
 sxl: tlc                # sxl to use, options are 'core' or 'tlc'
-sxl_version: 1.0.15     # sxl version to use
+sxl_version: 1.1        # sxl version to use
 components:           # components of local site, organized by type and name
   main:                 # type
     TC:                 # name
@@ -145,8 +147,8 @@ timeouts:             # timeouts
   watchdog: 0.2         # max time between receiving watchdogs, in seconds
   acknowledgement: 0.2  # max time unless a message we send is acknowledged, in seconds
 restrict_testing:       # restrict what tests are run, default is to run all
-  core_version: 3.1.5   # skip unless relevant for core 3.1.5
-  sxl_version: 1.0.13   # skip unless relevant for sxl 1.0.13
+  core_version: 3.2.1   # skip unless relevant for core 3.2.1
+  sxl_version: 1.1      # skip unless relevant for sxl 1.1
 secrets:                # place secrets or in a separate file, see below
   security_codes:       # RSMP security codes. there are no defaults for these
     1: '1111'           # level 1

docs/pages/writing.md

@@ -25,8 +25,8 @@ RSpec.describe "Traffic Light Controller" do
       expect {
         # request a non-existing status
         status_list = convert_status_list( S0000:[:status] )
-        site.request_status Validator.config['main_component'], status_list, collect: {
-          timeout: Validator.config['timeouts']['command_response']
+        site.request_status Validator.get_config('main_component'), status_list, collect: {
+          timeout: Validator.get_config('timeouts','command_response')
         },
         # normally we can't send S0000 because JSON Schema validation
         # will prevent it, but we can disable it for testing purposes

spec/site/core/aggregated_status_spec.rb

@@ -11,8 +11,8 @@
       Validator::Site.connected do |task,supervisor,site|
         prepare task, site
         log "Request aggregated status"
-        result = site.request_aggregated_status Validator.config['main_component'], collect!: {
-          timeout: Validator.config['timeouts']['status_response']
+        result = site.request_aggregated_status Validator.get_config('main_component'), collect!: {
+          timeout: Validator.get_config('timeouts','status_response')
         }
       end
     end

spec/site/core/disconnect_spec.rb

@@ -14,7 +14,7 @@
     # 2. When our supervisor does not acknowledge watchdogs
     # 3. Then the site should disconnect
     it 'is closed if watchdogs are not acknowledged', sxl: '>=1.0.7' do |example|
-      timeout = Validator.config['timeouts']['disconnect']
+      timeout = Validator.get_config('timeouts','disconnect')
       Validator::Site.isolated do |task,supervisor,site_proxy|
         supervisor.ignore_errors RSMP::DisconnectError do
           log "Disabling watchdog acknowledgements, site should disconnect"
@@ -37,7 +37,7 @@ def site_proxy.acknowledge original
     # 3. Then the site should not disconnect
     it 'is not closed if watchdogs are not received', sxl: '>=1.0.7', slow: true do |example|
       Validator::Site.isolated do |task,supervisor,site|
-        timeout = Validator.config['timeouts']['disconnect']
+        timeout = Validator.get_config('timeouts','disconnect')
 
         wait_task = task.async do
           site.wait_for_state :disconnected, timeout: timeout

spec/site/tlc/alarm_spec.rb

@@ -88,7 +88,7 @@ def verify_timestamp alarm, duration=1.minute
       Validator::Site.connected do |task,supervisor,site|
         prepare task, site
         alarm_code_id = 'A0302'   # what alarm to expect
-        timeout  = Validator.config['timeouts']['alarm']
+        timeout  = Validator.get_config('timeouts','alarm')
 
         log "Activating alarm #{alarm_code_id}"
         deactivate, component_id = with_alarm_activated(task, site, alarm_code_id) do |alarm, component_id|   # raise alarm, by activating input
@@ -165,7 +165,7 @@ def verify_timestamp alarm, duration=1.minute
               'aSp' => 'Suspend',
               'sS' => /Suspended/i
             },
-            timeout: Validator.config['timeouts']['alarm']
+            timeout: Validator.get_config('timeouts','alarm')
           ).collect!
         end
 
@@ -187,7 +187,7 @@ def verify_timestamp alarm, duration=1.minute
             m_id: resume.m_id,
             num: 1,
             query: {'aCI'=>alarm_code_id,'aSp'=>'Suspend','sS'=>'notSuspended'},
-            timeout: Validator.config['timeouts']['alarm']
+            timeout: Validator.get_config('timeouts','alarm')
           ).collect!
         end
         site.send_message resume

spec/site/tlc/clock_spec.rb

@@ -64,8 +64,8 @@
               :minute,
               :second,
             ] }
-            result = site.request_status Validator.config['main_component'], convert_status_list(status_list), collect!: {
-              timeout: Validator.config['timeouts']['status_update']
+            result = site.request_status Validator.get_config('main_component'), convert_status_list(status_list), collect!: {
+              timeout: Validator.get_config('timeouts','status_update')
             }
             collector = result[:collector]
             status = status_list.keys.first.to_s
@@ -81,8 +81,8 @@
             )
 
             max_diff =
-              Validator.config['timeouts']['command_response'] +
-              Validator.config['timeouts']['status_response']
+              Validator.get_config('timeouts','command_response') +
+              Validator.get_config('timeouts','status_response')
 
             diff = received - CLOCK
             diff = diff.round
@@ -114,14 +114,14 @@
               :second,
             ] }
 
-            result = site.request_status Validator.config['main_component'],
+            result = site.request_status Validator.get_config('main_component'),
               convert_status_list(status_list),
               collect!: {
-                timeout: Validator.config['timeouts']['status_response']
+                timeout: Validator.get_config('timeouts','status_response')
               }
             collector = result[:collector]
 
-            max_diff = Validator.config['timeouts']['command_response'] + Validator.config['timeouts']['status_response']
+            max_diff = Validator.get_config('timeouts','command_response') + Validator.get_config('timeouts','status_response')
             diff = Time.parse(collector.messages.first.attributes['sTs']) - CLOCK
             diff = diff.round
             expect(diff.abs).to be <= max_diff,
@@ -144,11 +144,11 @@
         prepare task, site
         site.with_watchdog_disabled do  # avoid time synchronization by disabling watchdogs
           with_clock_set CLOCK do
-            result = site.request_aggregated_status Validator.config['main_component'], collect!: {
-              timeout: Validator.config['timeouts']['status_response']
+            result = site.request_aggregated_status Validator.get_config('main_component'), collect!: {
+              timeout: Validator.get_config('timeouts','status_response')
             }
             collector = result[:collector]
-            max_diff = Validator.config['timeouts']['command_response'] + Validator.config['timeouts']['status_response']
+            max_diff = Validator.get_config('timeouts','command_response') + Validator.get_config('timeouts','status_response')
             diff = Time.parse(collector.messages.first.attributes['aSTS']) - CLOCK
             diff = diff.round
             expect(diff.abs).to be <= max_diff,
@@ -172,7 +172,7 @@
           with_clock_set CLOCK do
             result = set_functional_position 'NormalControl'
             collector = result[:collector]
-            max_diff = Validator.config['timeouts']['command_response'] * 2
+            max_diff = Validator.get_config('timeouts','command_response') * 2
             diff = Time.parse(collector.messages.first.attributes['cTS']) - CLOCK
             diff = diff.round
             expect(diff.abs).to be <= max_diff,
@@ -196,7 +196,7 @@
           with_clock_set CLOCK do
             result = set_functional_position 'NormalControl'
             collector = result[:collector]
-            max_diff = Validator.config['timeouts']['command_response']
+            max_diff = Validator.get_config('timeouts','command_response')
             diff = Time.parse(collector.messages.first.attributes['cTS']) - CLOCK
             diff = diff.round
             expect(diff.abs).to be <= max_diff,
@@ -224,7 +224,7 @@
           with_clock_set CLOCK do                           # set clock
             with_alarm_activated(task, site, 'A0302') do |alarm|   # raise alarm, by activating input
               alarm_time = Time.parse( alarm.attributes["aTs"] )
-              max_diff = Validator.config['timeouts']['command_response'] + Validator.config['timeouts']['status_response']
+              max_diff = Validator.get_config('timeouts','command_response') + Validator.get_config('timeouts','status_response')
               diff = alarm_time - CLOCK
               expect(diff.round.abs).to be <= max_diff,
                 "Timestamp of alarm is off by #{diff}s, should be within #{max_diff}s"
@@ -247,9 +247,9 @@
         site.with_watchdog_disabled do  # avoid time synchronization by disabling watchdogs
           with_clock_set CLOCK do
             log "Checking watchdog timestamp"
-            collector = RSMP::Collector.new site, task:task, type: "Watchdog", num: 1, timeout: Validator.config['timeouts']['watchdog']
+            collector = RSMP::Collector.new site, task:task, type: "Watchdog", num: 1, timeout: Validator.get_config('timeouts','watchdog')
             collector.collect!
-            max_diff = Validator.config['timeouts']['command_response'] + Validator.config['timeouts']['status_response']
+            max_diff = Validator.get_config('timeouts','command_response') + Validator.get_config('timeouts','status_response')
             diff = Time.parse(collector.messages.first.attributes['wTs']) - CLOCK
             diff = diff.round
             expect(diff.abs).to be <= max_diff,

spec/site/tlc/detector_logics_spec.rb

@@ -46,16 +46,14 @@
       Validator::Site.connected do |task,supervisor,site|
         prepare task, site
 
-        Validator.config['components']['detector_logic'].keys.each_with_index do |component, indx|
+        Validator.get_config('components','detector_logic').keys.each_with_index do |component, indx|
           force_detector_logic component, mode:'True'
-          Validator.config['main_component'] = Validator.config['main_component']
           wait_for_status(@task,
             "detector logic #{component} to be True",
             [{'sCI'=>'S0002','n'=>'detectorlogicstatus','s'=>/^.{#{indx}}1/}]
           )
 
           force_detector_logic component, mode:'False'
-          Validator.config['main_component'] = Validator.config['main_component']
           wait_for_status(@task,
             "detector logic #{component} to be False",
             [{'sCI'=>'S0002','n'=>'detectorlogicstatus','s'=>/^.{#{indx}}0/}]

spec/site/tlc/emergency_routes_spec.rb

@@ -33,7 +33,7 @@
     # 2. When we send M0005 to set emergency route.
     # 3. Then we should get a command responds confirming the change.
     it 'can be activated with M0005 and read with S0006', sxl: ['>=1.0.7','<1.2'] do |example|
-      emergency_routes = Validator.config['items']['emergency_routes']
+      emergency_routes = Validator.get_config('items','emergency_routes')
       skip("No emergency routes configured") if emergency_routes.nil? || emergency_routes.empty?
 
       def set_emergency_states task, emergency_routes, state
@@ -84,7 +84,7 @@ def disable_routes task, emergency_routes
         )
       end
 
-      emergency_routes = Validator.config['items']['emergency_routes']
+      emergency_routes = Validator.get_config('items','emergency_routes')
 
       skip("No emergency routes configured") if emergency_routes.nil? || emergency_routes.empty?
 

spec/site/tlc/invalid_command_spec.rb

@@ -14,15 +14,15 @@
       Validator::Site.connected do |task,supervisor,site|
         log "Sending M0001"
         command_list = build_command_list :M0001, :setValue, {
-          securityCode: Validator.config['secrets']['security_codes'][2],
+          securityCode: Validator.get_config('secrets','security_codes',2),
           status: 'NormalControl',
           timeout: 0,
           intersection: 0
         }
         result = site.send_command(
           'bad',
           command_list,
-          collect: { timeout: Validator.config['timeouts']['command_response'] },
+          collect: { timeout: Validator.get_config('timeouts','command_response') },
           validate: false     # disable validation of outgoing message
         )
         collector = result[:collector]
@@ -52,8 +52,8 @@
       Validator::Site.connected do |task,supervisor,site|
         log "Sending non-existing command M0000"
         command_list = build_command_list :M0000, :bad, {}
-        result = site.send_command Validator.config['main_component'], command_list,
-          collect: { timeout: Validator.config['timeouts']['command_response'] },
+        result = site.send_command Validator.get_config('main_component'), command_list,
+          collect: { timeout: Validator.get_config('timeouts','command_response') },
           validate: false     # disable validation of outgoing message
         collector = result[:collector]
         expect(collector).to be_an(RSMP::Collector)
@@ -81,8 +81,8 @@
             timeout: '0'
             # intentionally not setting 'status'
         }
-        result = site.send_command Validator.config['main_component'], command_list,
-          collect: { timeout: Validator.config['timeouts']['command_response'] },
+        result = site.send_command Validator.get_config('main_component'), command_list,
+          collect: { timeout: Validator.get_config('timeouts','command_response') },
           validate: false   # disable validation of outgoing message
         collector = result[:collector]
         expect(collector).to be_an(RSMP::Collector)
@@ -110,8 +110,8 @@
             intersection: '0',
             timeout: '0'
         }
-        result = site.send_command Validator.config['main_component'], command_list,
-          collect: { timeout: Validator.config['timeouts']['command_response'] },
+        result = site.send_command Validator.get_config('main_component'), command_list,
+          collect: { timeout: Validator.get_config('timeouts','command_response') },
           validate: false   # disable validation of outgoing message
         collector = result[:collector]
         expect(collector).to be_an(RSMP::Collector)

spec/site/tlc/invalid_status_spec.rb

@@ -17,7 +17,7 @@
         result = site.request_status(
           'bad',
           status_list,
-          collect: { timeout: Validator.config['timeouts']['status_response'] },
+          collect: { timeout: Validator.get_config('timeouts','status_response') },
           validate: false
         )
         collector = result[:collector]
@@ -48,8 +48,8 @@
         log "Requesting non-existing status S0000"
         status_list = convert_status_list( S0000:[:status] )
         result = site.request_status(
-          Validator.config['main_component'], status_list,
-          collect: { timeout: Validator.config['timeouts']['status_response'] },
+          Validator.get_config('main_component'), status_list,
+          collect: { timeout: Validator.get_config('timeouts','status_response') },
           validate: false
         )
         collector = result[:collector]
@@ -72,8 +72,8 @@
         log "Requesting S0001 with non-existing status name"
         status_list = convert_status_list( S0001:[:bad] )
         result = site.request_status(
-          Validator.config['main_component'], status_list,
-          collect: { timeout: Validator.config['timeouts']['status_response'] },
+          Validator.get_config('main_component'), status_list,
+          collect: { timeout: Validator.get_config('timeouts','status_response') },
           validate: false
         )
         collector = result[:collector]