Automated tests

With Pororoca, you can make automated tests with .NET testing tools, such as xUnit. These tests can be executed in a pipeline or via command line, sending requests to a server.

To create and run these tests, you need to have .NET 6 or later in your computer.

Creating the test project

Create a test project through Visual Studio or via command line. For this latter option, type the following command on your console:

mkdir MyPororocaTest
cd ./MyPororocaTest/
dotnet new xunit
# other testing libraries can be used

mkdir MyPororocaTest
cd ./MyPororocaTest/
dotnet new xunit
# other testing libraries can be used

After that, in the created test project, the .csproj file must be edited to include the Pororoca.Test NuGet package.

If you are using .NET 6 in your test project, the Pororoca.Test version needs to be 1.*.*. Check the Automated Tests documentation for Pororoca.Test v1, if that is your case.

Be aware that if you will run your unit tests on a Linux machine and those tests include HTTP/3, msquic needs to be installed. Use msquic v1 for .NET 6 and msquic v2 for .NET 7.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- TargetFramework needs to be .net6.0 or higher -->
    <!-- Pororoca.Test v1 uses .net6.0 -->
    <!-- Pororoca.Test v2 uses .net7.0 -->
    <TargetFramework>net7.0</TargetFramework>
    …
  </PropertyGroup>
  <ItemGroup>
    <!-- The line below adds Pororoca.Test package to the project -->
    <PackageReference Include="Pororoca.Test" Version="2.0.1" />
    …
  </ItemGroup>

</Project>

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- TargetFramework needs to be .net6.0 or higher -->
    <!-- Pororoca.Test v1 uses .net6.0 -->
    <!-- Pororoca.Test v2 uses .net7.0 -->
    <TargetFramework>net7.0</TargetFramework>
    …
  </PropertyGroup>
  <ItemGroup>
    <!-- The line below adds Pororoca.Test package to the project -->
    <PackageReference Include="Pororoca.Test" Version="2.0.1" />
    …
  </ItemGroup>

</Project>

Making your first test

The code below shows how to use the Pororoca.Test in a xUnit test. First, it loads a Pororoca collection from a file. Then, defines the environment that will be used.

using Xunit;
using System.Net;
using Pororoca.Test;

namespace Pororoca.Test.Tests;

public class MyPororocaTest
{
    private readonly PororocaTest pororocaTest;

    public MyPororocaTest()
    {
        string filePath = @"C:\Tests\MyCollection.pororoca_collection.json";
        pororocaTest = PororocaTest.LoadCollectionFromFile(filePath)
                                   .AndUseTheEnvironment("Local");
    }

    [Fact]
    public async Task Should_get_JSON_successfully()
    {
        var res = await pororocaTest.SendRequestAsync("Get JSON");

        Assert.NotNull(res);
        Assert.Equal(HttpStatusCode.OK, res.StatusCode);
        Assert.Equal("application/json; charset=utf-8", res.ContentType);
        Assert.Contains("\"id\": 1", res.GetBodyAsText());
    }
}

using Xunit;
using System.Net;
using Pororoca.Test;

namespace Pororoca.Test.Tests;

public class MyPororocaTest
{
    private readonly PororocaTest pororocaTest;

    public MyPororocaTest()
    {
        string filePath = @"C:\Tests\MyCollection.pororoca_collection.json";
        pororocaTest = PororocaTest.LoadCollectionFromFile(filePath)
                                   .AndUseTheEnvironment("Local");
    }

    [Fact]
    public async Task Should_get_JSON_successfully()
    {
        var res = await pororocaTest.SendRequestAsync("Get JSON");

        Assert.NotNull(res);
        Assert.Equal(HttpStatusCode.OK, res.StatusCode);
        Assert.Equal("application/json; charset=utf-8", res.ContentType);
        Assert.Contains("\"id\": 1", res.GetBodyAsText());
    }
}

There are methods in the PororocaTest class to set values of variables during the tests executions. They can be used to set an authentication token, for example:

pororocaTest.SetCollectionVariable("MyAuthenticationToken", "token_auth");

pororocaTest.SetCollectionVariable("MyAuthenticationToken", "token_auth");

The test project Pororoca.Test.Tests can guide you - it shows how to use the Pororoca.Test package, how to load the collection file and how to set variables.

WebSocket tests

You can also make Pororoca tests for WebSockets. The code below shows an example:

[Fact]
public async Task Should_connect_and_disconnect_with_client_closing_message_successfully()
{
    // GIVEN AND WHEN
    var ws = await this.pororocaTest.ConnectWebSocketAsync("WebSocket HTTP1");
    // THEN
    Assert.Equal(PororocaWebSocketConnectorState.Connected, ws.State);

    // WHEN
    await ws.SendMessageAsync("Bye");
    // THEN
    Assert.Null(ws.ConnectionException);
    Assert.Equal(PororocaWebSocketConnectorState.Disconnected, ws.State);

    var msg = Assert.IsType<PororocaWebSocketClientMessageToSend>(ws.ExchangedMessages[0]);
    Assert.Equal(PororocaWebSocketMessageType.Close, msg.MessageType);
    Assert.Equal("Adiós", msg.Text);
}

[Fact]
public async Task Should_connect_and_disconnect_with_client_closing_message_successfully()
{
    // GIVEN AND WHEN
    var ws = await this.pororocaTest.ConnectWebSocketAsync("WebSocket HTTP1");
    // THEN
    Assert.Equal(PororocaWebSocketConnectorState.Connected, ws.State);

    // WHEN
    await ws.SendMessageAsync("Bye");
    // THEN
    Assert.Null(ws.ConnectionException);
    Assert.Equal(PororocaWebSocketConnectorState.Disconnected, ws.State);

    var msg = Assert.IsType<PororocaWebSocketClientMessageToSend>(ws.ExchangedMessages[0]);
    Assert.Equal(PororocaWebSocketMessageType.Close, msg.MessageType);
    Assert.Equal("Adiós", msg.Text);
}

Running the tests

You can run the tests on Visual Studio or executing dotnet test through the command line.

Why automated tests outside the GUI?

Other HTTP inspection tools, like Postman and SoapUI, have their testing areas inside the GUI. In Pororoca, the choice was to have tests done outside the GUI, for the following reasons.

• Automated tests often require a setup, like running scripts in a database to pre-add or pre-remove data, or pulling information from an external data source, to compare with responses from the APIs. Testing in a GUI does not allow to easily do that, whereas testing in an isolated program does.

• You can freely choose your assertion and testing frameworks, such as xUnit and FluentAssertions.

• By having the tests in a dotnet project, they are already prepared to be run in a CI, only requiring a dotnet test step to execute them.