Work in progress

Developing your own steps

A step in STC is a command that is executed by a shell. After execution of the command is complete, STC checks if the command returned the expected status. If the expected status is not returned, and error is generated and the enclosing test fails. Steps are the basic build blocks for STC scenarios.

A step may be written in any language, as long as it can be called from the shell command line and it can return a status using the exit() system call. Common choices for implementing STC steps are shell scripts and python programs.

Basic step syntax

A step contains a name, a command to execute, an optional environment, and optional step names it depends on:

<step name="Cleanup-Mininet" exec="onos-mininet cleanup" requires="~Stop-Mininet,Setup-Network"/>

In this step, the name is "Cleanup-Mininet". The name is used to refer to this step in the dependency list of other steps, and is also used to display information about the step as it is executing. The exec attribute specifies the command to run, in this case "onos-mininet cleanup". The requires attribute Is a comma separated list of step names that must be complete before this step can execute. Specifying a tilde character before a step name ("~") indicates that this is a soft dependency, and the stop should execute regardless of the status of the dependent step. If no tilde is specified, this is a hard dependency, and the step will fail if the dependent step failed.

Sample Step Using a Shell Script

As a sample STC test, we are going to write an STC scenario that tests the ONOS CLI "maps" command. The script will take as parameters the ONOS node to execute on, the name of a map, and an ID to use when returning data. More about returning data a little later.

#!/bin/bash

# -----------------------------------------------------------------------------
# Invokes the ONOS CLI and looks for a 'maps' entry with the given name
# -----------------------------------------------------------------------------

NODE=$1
MAP=$2
ID=$3

map_text=`( onos ${NODE} onos:maps ) | grep ${MAP}`

if [ $? -ne 0 ]; then
    exit 1
fi

map_size=`echo ${map_text} | sed s#^.*size=##`
echo "@stc ${ID}Size=${map_size}"

Scripts may return values to the calling step by using the special syntax '@stc name=value' in the standard output. STC parses these special tags and allows a step to interrogate the values to be sure that the data values are correct. In this script, we have added the ID string to the name portion of the tag so that the script can be invoked multiple times from the same scenario.

In our sample script, the ONOS CLI is called, grep is used to search for the given entry, and then the script returns the size of the map. The ID we provided to the call is used to uniquely identify the results of this call so that we can check for correctness later.

Now to put it all together, we have to write a step to call the script, and then another step to test the value of the size of the map. Here is a section of a scenario that performs these operations:

<!-- Check map known to have at least 50 entries -->
<step name="Maps-Cli.Find-Intent-Mapping2-Shell"
      exec="onos-find-map ${OCI} onos-app-ids appIdsMapping"/>
<step name="Maps-Cli.Check-App-Ids-Mapping-Shell" requires="^"
      exec="test ${appIdsMappingSize} -gt 50"/>

Things to include:

• Setting debug=true env variables
• conditional attributes: if, unless
• Importing other scenarios
• Namespaces