Getting started

This guide provides a quick tutorial on setting up and running an OpenTAP project using the OpenTAP Runner and NATS Server. The tutorial will walk you through installing necessary packages, setting up a basic C# Console project, and interacting with the Runner.

Compatibility Runner Client 3.x targets the asynchronous API and is wire-compatible with Runner 2.x. Use Runner Client 2.x only when talking to Runner 1.x installations.

Prerequisites

• An OpenTAP installation

Starting the Runner

In an OpenTAP installation, install the two OpenTAP Packages, “Runner” and “NATS Server”:

./tap image install "Runner,NATS Server" --merge

Then start the Runner to start the OpenTAP Runner and the NATS Server:

./tap runner start

The NATS Server process will by default start on nats://127.0.0.1:20111 and the Runner will listen on the OpenTap.Runner.{MachineName} subject.

Docker images

OpenTAP Runner publishes two Linux images to GHCR for Keysight teams:

• Static (version-tagged) image: ghcr.io/opentap/runner:<version>
• Updatable image: ghcr.io/opentap/runner:updatable (and :updatable-beta / :updatable-rc for prereleases)

Static images keep the OpenTAP installation inside the image and only expose data folders as volumes. Updatable images mount the full /opt/tap installation so in-container updates persist across restarts.

Example: run a static image and persist data

docker run --rm -p 20111:20111 -p 20116:20116 \
  -v runner-storage:/opt/tap/Storage \
  -v runner-logs:/opt/tap/SessionLogs \
  -v runner-settings:/opt/tap/Settings \
  ghcr.io/opentap/runner:<version>

Example: run the updatable image

docker run --rm -p 20111:20111 -p 20116:20116 \
  -v runner-installation:/opt/tap \
  ghcr.io/opentap/runner:updatable

These images are currently only available to Keysight teams. If you are outside Keysight and are interested in access, reach out via the contact information on the contact page.

Creating a C# Console Project

1. Create a new C# Console project:

mkdir MyApp
cd MyApp
dotnet new console

1. Add the Runner Client package:

dotnet add package OpenTAP.Runner.Client --version 3.*

1. Modify Program.cs to interact with the Runner. The Runner Client 3.x surface is asynchronous, so we use top-level await (available in recent .NET templates):

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using NATS.Client.Core;
using OpenTap.Runner.Client;

await using INatsConnection connection = new NatsConnection(new NatsOpts { Url = RunnerClient.DefaultUrl });
await connection.ConnectAsync();
RunnerClient runnerClient = new RunnerClient(connection);
SessionClient sessionClient = await runnerClient.StartSessionAsync();

sessionClient.ConnectSessionLogs(handleSessionLogs);

static Task handleSessionLogs(LogList? logList)
{
    if (logList?.Logs == null)
        return Task.CompletedTask;

    foreach (var log in logList.Logs)
        Console.WriteLine($"{log.Source,-12}: {log.Message}");

    return Task.CompletedTask;
}

// Get the available step types (Similar to "Add new step" dialog)
List<TestStepType> stepTypes = await sessionClient.GetStepTypesAsync();

// Get the current test plan from the session
TestPlan testPlan = await sessionClient.GetTestPlanAsync(null);

// Add a delay step to the test plan
testPlan.ChildTestSteps.Add(stepTypes.First(step => step.TypeName.Contains("Delay")));

// Update the test plan on the session
testPlan = await sessionClient.SetTestPlanAsync(testPlan);

// Give the test plan a name
await sessionClient.SetTestPlanNameAsync("My Testplan");

// Start the test plan
RunStatus runStatus = await sessionClient.RunTestPlanAsync(new List<Parameter>());

// Wait for the test plan to finish
while (runStatus.SessionState != SessionState.Idle)
{
    await Task.Delay(250);
    runStatus = await sessionClient.GetStatusAsync();
}

// Shutdown the session
await sessionClient.ShutdownAsync();
await runnerClient.ShutdownSessionAsync(sessionClient.Id);

This code connects, starts a Session, connects to session logs, creates a test plan and executes it. After execution finishes, the session is closed.

1. Run the project:

dotnet run

The expected output of dotnet run:

TestPlan    : -----------------------------------------------------------------
TestPlan    : Starting TestPlan 'My Testplan' on 04/05/2023 14:36:25, 1 of 1 TestSteps enabled.
TestPlan    : Saved Test Plan XML [1.66 ms]
Settings    : No settings file exists for TestPlanRunPackageParameterMonitor. A new instance with default values has been created. [200 us]
TestPlan    : PrePlanRun Methods completed [2.46 ms]
TestPlan    : "Delay" started.
TestPlan    : "Delay" completed. [107 ms]
TestPlan    : Test step runs finished. [119 ms]
Summary     : ----- Summary of test plan started 04/05/2023 14:36:25 -----
Summary     :  Delay                                             107 ms
Summary     : ------------------------------------------------------------
Summary     : -------- Test plan completed successfully in 199 ms --------

With these steps, you have successfully set up and run an application that remotely executed a testplan using the OpenTAP Runner and NATS Server.

We can now stop the OpenTAP Runner (and NATS Server) by sending CTRL+C in the command prompt with the Runner.