states.adoc

qDup states

The state is where qDup stores values during a run and how scripts can introduce variability into a run. The YAML is converted to JSON and can be used in any state value pattern ${{…​}}.

Commands can reference state variables by name with ${{name}} and regex can define new entries with standard java regex capture groups (?<name>.*)

- sh: tail -f /tmp/server.log
  watch:
- regex : ".*? WFLYSRV0025: (?<eapVersion>.*?) started in (?<eapStartTime>\\d+)ms.*"
  then:
  - log : eap ${{eapVersion}} started in ${{eapStartTime}}
  - ctrlC

Defining state

states:
  count: 100
  duration: 300
  users:
  - name: bill
    score: 2
  - name: beth
    score: 22

The YAML state is globally available but if scripts updated the global state by default then regex: (?<name>.*) in one script and set-state: name in another script would collide. qDup avoids script state collision by using a tiered approach to state.

• Shared Global Run State

  • Shared Host State

    • Script State

Each script defaults new values to its own private state. The values can target the host or run state by putting a prefix before the state name.

set-state: RUN.name bill

The RUN. prefix tells qDup to add the state entry to the global run state which is shared across all scripts

set-state: HOST.name bill

The HOST. prefix tells qDup to add the state entry to the shared host state which is schared by all scripts on the current host.

Accessing state

qDup state is accessed using state expressions

${{count}}

where count is a state entry. Expressions can also access JSON members

${{users[0].name}}

expressions can include a default value with a : separator

${{count:100}}

Scripts do not need to use the prefix to access values from the host or run state. The prefix can be used to only accept values from the target state but this is rarely necessary.

- sh: echo "hi ${{name}}" #will check default, then host, then run state
- sh: echo "who is ${{RUN.name}}" #will only check the run state

JavaScript expressions

qDup can evaluate javascript in a javascript state expression

The ${{= state prefix tells qDup to use the javascript engine to evaluate the content. This lets us use javascript methods, string templates, any arithmetic operations. A : can also be used to define a default value should any of the state variable names not be defined

 - sh: tail -f /tmp/server.log
   timer:
     ${{= ${{RAMP_UP}} + ${{MEASURE}} + ${{RAMP_DOWN}} : 100}}:
     - echo : "${{= ${{RAMP_UP}}+${{MEASURE}}+${{RAMP_DOWN}} : 100}}ms have has elapsed"
     - echo : "$[[> $[[RAMP_UP]]+$[[MEASURE]]+$[[RAMP_DOWN]] _ 100]]ms have has elapsed"
       prefix: "$[[" #use a custom state reference prefix
       suffix: "]]" #use a custom state reference suffix
       js-prefix: ">" #used after state prefix to tell qDup to use the javascript engine
       separator: "_" #use a custom separator between state expression and the default value

${{= range(1,10) }}

The javascript state expression can include nested state expressions which are evaluated before the javascript executes and can include a default just like state expressions.

${{= "${{users[0].name}}".toLowerCase() : john }}

JavaScript globals

The javascript engine uses ECMAScript 2020 with graaljs. qDup provides a global read-only JSON representation of the current state, signals, and counters under the QD global name. This was added recently and is subject to change as we work on the api.

qDup also allows users to define global methods to help with common tasks, see globals

Reserved names

qDup reserves the ENV state prefix to add information about the qDup execution.

• ENV.SCRIPT_DIR the path to the script that loaded the script. This helps reference files store along side scripts e.g. cp ${{ENV.SCRIPT_DIR}}/secrets.properties /tmp/

• ENV.ABORTED set to "true" when a run aborts, otherwise it is not defined. Cleanup scripts can read-state: ${{ENV.ABORTED}} to control cleanup steps