The Step CLI can run an entire Automation Package on your own machine, without a Step server. It uses a local agent provisioning which provisions the required agents as separate processes. The Keywords therefore run in the same isolation, and against the same agents, locally and centrally.

An agent is started the first time a Plan needs it, and is then kept running and shared by all the Plans the command executes, until the command ends. Nothing has to be installed or configured for Java Keywords — the CLI ships the Java agent. Other Keyword types need their runtime on the machine, and are covered under Prerequisites.

Quick start

Run the ap execute command with the --local option from the folder containing your automation-package.yaml:

step ap execute --local

All Plans of the package are executed, one after the other, and the result of each is printed as it finishes. A failing Plan does not stop the ones that follow, but the command exits with an error once they are all done.

Point at a package somewhere else with --package, and select a subset of the Plans with the same filtering options as a remote execution:

step ap execute --local --package=./my-package --includeCategories=Smoke

An Automation Package using a package library runs locally too:

step ap execute --local --library=./my-library.jar

Supported Keyword types

Which agent a Keyword runs on is decided by its type, and each agent has its own requirements on the machine:

Two of these accept further optional environment variables, applied to local executions only: SOAP_UI_REPORT and SOAP_UI_FORCE_OSS for SoapUI, and ORYON_ERROR_HANDLER for Oryon.

When a Plan needs a Keyword type this machine cannot serve, the execution stops before anything runs, with a message naming the missing type and what to do about it:

This plan requires agent types which are not available for local execution: node.
The Node.js agent runs on Node.js, which is not installed on this machine.

Prerequisites

Java Keywords

Nothing to install. The Java agent is shipped inside the CLI and extracted on first use, into the workspace where it is kept for later runs. It is started as a separate process, with the same Java runtime the CLI is running on.

Use --localAgentJava to run an agent you installed yourself instead of the embedded one.

Node.js Keywords

node must be runnable from your PATH. The agent itself ships with the CLI, so nothing has to be installed and nothing is downloaded: it is extracted into the workspace on first use and reused afterwards.

To run a different one, point --localAgentNode at it. It accepts either shape an installed agent comes in: the step-node-agent package itself, which is what npm install -g step-node-agent and an unpacked archive leave behind, or a directory containing it in node_modules, which is what npm install ./step-node-agent-<version>.tgz leaves.

.NET Keywords

The .NET agent is a platform-specific binary distribution and is never installed by the CLI. Install the Step .NET agent for your platform and point the CLI at it, either with --localAgentDotNet or with the STEP_DOTNET_AGENT_HOME environment variable. Both accept the agent distribution directory or its bin directory.

Options

These options apply to local executions only. Like every CLI option, they can also be set in a configuration file, which is the most practical way to configure them once for a project.

• --localAgentJava=<Path> the directory of an installed Step Java agent to use instead of the one embedded in the CLI
• --localAgentNode=<Path> the directory of an installed Step Node.js agent to use instead of the one embedded in the CLI. Either the step-node-agent package itself, or a directory containing it in node_modules
• --localAgentDotNet=<Path> the directory of an installed Step .NET agent. Defaults to the STEP_DOTNET_AGENT_HOME environment variable
• --localAgentWorkDir=<Path> the directory the local agents are installed and run in. Defaults to a folder in the system temporary directory
• --localAgentMaxTokens=<Count> the number of Keywords one agent can run in parallel. Every agent is started with this many tokens, regardless of what the Plan requires: a Plan needing more runs its parallel steps in sequence beyond this number, and a warning is displayed. Default: 5
• --localAgentStartTimeout=<Seconds> how long to wait for an agent to start and connect. Default: 60
• --localAgentVmArgs=<Arg> an additional JVM argument for the Java agent. Repeat the option to pass several arguments, and wrap in double quotes any argument containing spaces

Example, in a stepcli.properties file:

localAgentDotNet=C:/step/dotnet-agent
localAgentMaxTokens=10
localAgentStartTimeout=120

Where the agents run

The CLI works in a single directory, step-cli-local-agents in the system temporary directory unless --localAgentWorkDir says otherwise. It holds two kinds of things:

• the agents and libraries the CLI installed, kept between runs — this is what spares you an installation on every execution;
• one throw-away directory per agent and per grid, deleted when the command ends.

A CLI that is killed never gets to clean up, so the throw-away directories left behind by a previous run are removed at the start of the next one. The installed agents are never swept.

How the agents are reused

There is one agent per agent type — one Java agent, one Node.js agent, and so on — no matter how many Plans the command executes:

• Started on first need. An agent is started when the first Plan requiring its type is executed. A package whose Plans only use Java Keywords never starts a Node.js agent.
• Shared by the following Plans. The next Plans run on the same agent rather than on a new one, which spares them its start-up time and keeps what the agent prepares between Keywords, such as the workspace and the installed dependencies of a Node.js Keyword project.
• Replaced if it dies. An agent that crashes or no longer responds is restarted before the next Plan requiring it. Its last output is printed as a warning.
• Stopped at the end of the command.

Seeing what the agents do

Local executions are quiet by default: the agents are started, used and stopped without printing anything of their own.

• --verbose prints what the agents log, along with the applied configuration and the stack traces of errors.
• --debug implies --verbose and additionally raises the Step loggers to debug level, in the CLI and in the agents.

Troubleshooting

This plan requires agent types which are not available for local execution: …

The Plan uses a Keyword type no agent on this machine can run. The message names each missing type, followed by what to install or configure for it. See Prerequisites.

An agent fails to start, or does not connect in time

The execution reports what the agent printed before it gave up, which is usually enough — a missing runtime, a port conflict, an unreadable configuration. Run again with --verbose for the agent’s full output. If the machine is simply slow, or an agent is being extracted or installed on first use, raise --localAgentStartTimeout.

Debugging a Java Keyword

Attach a debugger to the Java agent, which is where the Keyword actually runs (refer to your IDE debugger documentation for more details):

step ap execute --local --localAgentVmArgs=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005

Logging Customization

For advanced troubleshooting, you can customize the logging configuration by providing a custom Logback XML file.

• For the CLI:

  • Pass it as an environment variable:
    JAVA_TOOL_OPTIONS=-Dlogback.configurationFile=<path/to/logback.xml>
  • Add the system property to step.l4j.ini alongside step.exe (create the file if it does not exist):
    -Dlogback.configurationFile=<path/to/logback.xml>

• For the Java Agent:

  • Pass the configuration using the CLI flag:
    --localAgentVmArgs=-Dlogback.configurationFile=<path/to/logback.xml>

Limitations