1. Home
  2. Project Configuration
  3. Specification
  4. Script

The Script Specification

Overview

Key/Property Value
body String, the actual script being executed.
description String.
environment_variables Map of strings. Subject to [inheritance].
exclusive_executor_resource String, see exclusive_executor_resource on this page.
ignore_abort Boolean, defaults to false. The script will not be skipped or aborted if set to true.
ignore_state Boolean, defaults to false. The state of this will not be taken into account for the aggregate state of the trial.
key String, defaults to the key in the scripts map. Uses to reference this script in start_when for example.
name String.
start_when Map of maps, see start_when and terminate_when on this page.
template_environment_variables Boolean, defaults to true.
terminate_when Map of maps. Opposite of start_when, each value specifies when to abort a script prematurely.
timeout String, representing a duration, defaults to 3 minutes. Determines when a script will be forcefully terminated.

The exclusive_executor_resource Property

The exclusive_executor_resource prevents two (or more) scripts with the same value to be executed in parallel on the same executor. The value is honored across scripts belonging to different trials/tasks, which is the prevalent use case.

The value is a string which can be templated. See also the templating page. Templating is always enabled: {{ and }} is to be avoided if no templating is intended.

If a script with a certain value is currently executing and an other script with the same value becomes eligible for being started, i.e. it fulfills the conditions given by start_when, its state will move from pending to waiting. It will be started when the "resource becomes available".

There are no guarantees with respect to the order if there are multiple scripts with the same value in waiting state.

Deadlock situations are impossible because every script has only one exclusive_executor_resource property.

 1environment_variables:
 2  RUBY_VERSION: 2.2.4
 3scripts:
 4  bundle:
 5    # never run `bundle install` in parallel,
 6    # it is likely to break your ruby installation
 7    exclusive_executor_resource: "ruby_{{RUBY_VERSION}}"
 8    bundle: |
 9      set -eux
10      rbenv shell $RUBY_VERSION
11      bundle install
12

The start_when and terminate_when Properties

The starte_when property is used to define dependencies between scripts belonging to the same trial. The article article Testing Services has further information about the ratio of this feature.

The terminate_when property defines conditions to specify premature termination of a script. It is not as useful as start_when property. It is mostly useful to achieve faster termination of a running script when some other script fails.

Both properties use a map of maps to specify a collection of dependencies. The keys can be freely chosen, for example to describe the dependency. The items are combined with logical conjunction: a script will be started if and only if all dependencies are satisfied.

Key/Property Value
script_key String, the key of the script to reference.
states Array of states out of: aborted, defective, executing, failed, passed, pending, skipped, waiting. 
 1scripts:
 2  prepare:
 3    body: do some preparing
 4  run-service:
 5    body: run some service and keep it running
 6    terminate_when:
 7      'test is in terminal state':
 8        script_key: test
 9        states: ['aborted', 'deffective', 'failed', 'passed', 'skipped']
10    ignote_state: true
11  test:
12    body: test
13    start_when:
14      'prepared':
15        script_key: prepare
16        states: [ "passed" ]
17      'service is running':
18        script_key: run-service
19        states: [ "executing"]
20  cleanup:
21    body: do some cleanup
22    start_when:
23      'start when test is in terminal state':
24        script_key: test
25        states: ['aborted', 'deffective', 'failed', 'passed', 'skipped']
26