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.

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 });

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.TypeDisplay.Name == "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.