Accelergreat.Xunit 3.0.0-beta.1

uid: DeveloperDocumentation.Index

Ultra Fast Integration Tests

Accelergreat your tests.

Write and execute efficient and high-performance integration tests with ease using Accelergreat. It is a powerful .NET integration testing solution that automatically provisions and manages external dependencies for your tests, such as databases and APIs. Simplify your integration testing development process today with Accelergreat.

Overview

Accelergreat is a new and innovative testing platform designed to make integration testing easier.

Integration tests are essential to ensuring your code works and stays working. However, they have been challenging to write and run quickly in the past, earning a reputation as a problem area in the development world.

With Accelergreat we intend to make this a problem of the past by doing all the hard work for you.

Accelergreat currently supports xUnit and plans to support other test runners in the future.

Quality

We take pride in writing clean, quality code and use SonarCloud to scan our code for quality and security issues. This adds an extra layer of assurance that the code we ship is safe for your codebase to consume.

Version

Accelergreat follows Semantic Versioning 2.0.0 for releases.

Packages

• Accelergreat
• Accelergreat.EntityFramework
• Accelergreat.EntityFramework.InMemory
• Accelergreat.EntityFramework.PostgreSql
• Accelergreat.EntityFramework.Sqlite
• Accelergreat.EntityFramework.SqlServer
• Accelergreat.Web
• Accelergreat.Xunit

Download

You can download Accelergreat packages from NuGet.org.

Configuration

Accelergreat supports the overriding of configuration for managed external dependencies such as databases.

Accelergreat will read the following files in the root level of your test projects that have the CopyToOutputDirectory setting set to Always or PreserveNewest:

• accelergreat.json
• accelergreat.{environment}.json

accelergreat.{environment}.json is supported to allow you to have different configurations for your local machine and CI pipeline.

{environment} is defined by setting an environment variable called ACCELERGREAT_ENVIRONMENT.

A schema has been provided for the configuration files. An example is shown below:

{
    "$schema": "https://cdn.accelergreat.net/configuration/3.0.0-beta.1/schema.json#"
}

Getting started

Components

To further understand components beyond what the below getting started guide shows, read about all the different components Accelergreat offers and to understand how to build your own components. Please follow this guide.

Example use case

Accelergreat has been designed with modularity and flexibility in mind. Whilst the example we have provided below may not match your specific use case, this example was chosen to best show the capabilities of Accelergreat. It should be an effective reference point for your own implementations.

To see other examples, you can look on our GitHub examples repo.

Database (Entity Framework SQL Server) + Web API integration test

Process

1. Install the required packages
2. Create the Accelergreat Components
   1. Database component class(es)
   2. Web Api component class(es)
3. Create an Accelergreat Startup class
4. Write your first Accelegreat Integration Test

Install the required packages

• Accelergreat.EntityFramework.SqlServer
• Accelergreat.Web
• Accelergreat.Xunit

Create the Accelergreat Components

One of the core features of Accelergreat is the concept of components. A component represents a dependency for your tests. For example a database or a web API.

To further understand components beyond what this getting started guide shows, read about all the different components Accelergreat offers and to understand how to build your own components. Please follow this guide.

In our example we only need two components. One for our SQL Server database, and one for our Web API.

Database component

Create a class that inherits from SqlServerEntityFrameworkDatabaseComponent.

If you need to override any of the configuration values, see SqlServerEntityFrameworkConfiguration for the defaults.

using Accelergreat.EntityFramework.SqlServer;
using Microsoft.Extensions.Configuration;

namespace ExampleTestProject.Components;

public class ExampleDatabaseComponent : SqlServerEntityFrameworkDatabaseComponent<ExampleDbContext>
{
    public ExampleDatabaseComponent(IConfiguration configuration) : base(configuration)
    {
    }
}

Web API component

To interact with a .NET Web API in our integration tests, we need to create a Web App Component. (If you need to create a Microservice Architecture then follow this guide

Web app components run an instance of the API defined by the Web API startup class passed into the generic type parameter. The following steps will set up a component for you:

1. Create a class derived from WebAppComponent.
2. Inject the database connection string(s).
3. [Optional] overriding appsettings.

Create the class derived from WebAppComponent

To create a Web App Component, create a class that inherits from WebAppComponent and pass in your Web API startup class as the generic type parameter.

Using a Startup class

using System.Collections.Generic;
using Accelergreat.Web;
using Accelergreat.Web.Extensions;
using Microsoft.Extensions.Configuration;

namespace ExampleTestProject.Components;

public class ExampleApiComponent : WebAppComponent<ExampleApi.Startup>
{
    protected override void BuildConfiguration(
        IConfigurationBuilder configurationBuilder,
        IReadOnlyAccelergreatEnvironmentPipelineData accelergreatEnvironmentPipelineData)
    {
        configurationBuilder.AddEntityFrameworkDatabaseConnectionString<ExampleDbContext>(
            "ExampleConnectionStringName", accelergreatEnvironmentPipelineData);
    }
}

Using a Program class (minimal APIs)

With the recent introduction of minimal apis in Aspnet core, you can now configure your application entirely in Program.cs . The Progam class is now in the global App Domain as an internal class of the Api assembly. If you are using miniminal apis then you will have to expose InternalsVisibleTo to the Test Assembly by editing the csproj file of the Api project:

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

...

	<ItemGroup>
		<InternalsVisibleTo Include="ExampleTestProject" />
	</ItemGroup>
...

using System;
using System.Collections.Generic;
using Accelergreat.EntityFramework.Extensions;
using Accelergreat.Environments;
using Accelergreat.Web;
using GuestAndActivities.Data.Contexts;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;

namespace ExampleTestProject.Components;

internal class ExampleApiComponent : WebAppComponent<Program>
{

    protected override void BuildConfiguration(
            IConfigurationBuilder configurationBuilder,
            IReadOnlyAccelergreatEnvironmentPipelineData accelergreatEnvironmentPipelineData)
    {
        configurationBuilder.AddEntityFrameworkDatabaseConnectionString<ExampleDbContext>(
            "ExampleConnectionStringName", accelergreatEnvironmentPipelineData);
    }
}

Inject the database connection string(s)

In the examples above, we need to provide the database connection string to the Web API configuration a database connection string. We do this by overriding > BuildConfiguration and calling configurationBuilder.AddEntityFrameworkDatabaseConnectionString.

Create a Startup class

To create a working Accelergreat Start up class, follow these three important steps:

Create the class

Create a Startup class in your test project that implements IAccelergreatStartup.

Add the Assembly Attribute**

Accelergreat extends the xunit test framework, we have provided an assembly attribute that will instruct xunit to use the Accelergreat extended xunit test framework.

Important In the Startup file, add assembly attribute UseAccelergreatXunitTestFramework. Without this, the Startup code will not be executed.

Registering components in their dependent order (least dependent last)**

Lastly we need to register our components. In the ConfigureServices implementation, call services.AddAccelergreatComponent for each component as the type parameter.

Important The order in which components are initialized is defined by the order they are registered.

In our example, we need to initialize the database before the web API so that it can access the database connection string.

using Accelergreat.Xunit;
using Accelergreat.Xunit.Attributes;
using ExampleTestProject.Components;
using Microsoft.Extensions.DependencyInjection;

[assembly: UseAccelergreatXunitTestFramework]

namespace ExampleTestProject;

public class Startup : IAccelergreatStartup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAccelergreatComponent<ExampleDatabaseComponent>();
        services.AddAccelergreatComponent<ExampleApiComponent>();
    }
}

Write your first Accelegreat Integration Test

Now that we've got everything set up, we're going to write our first test.

For this example, we'll also be using FluentAssertions to keep our assertion code clean and easy to read. We'll also follow the Arrange Act Assert (AAA) pattern:

Arrange Set up and insert our test data

Act Call the API endpoint

Assert Validate that the response data is correct

Create a test that that inherits from AccelergreatXunitTest.

using System.Threading.Tasks;
using Accelergreat.Environments.Pooling;
using Accelergreat.Xunit;
using ExampleTestProject.Components;
using FluentAssertions;
using Newtonsoft.Json;
using Xunit;

namespace ExampleTestProject.Tests;

public class ExampleTests : AccelergreatXunitTest
{
    public ExampleTests(IAccelergreatEnvironmentPool environmentPool) : base(environmentPool)
    {
    }

    [Fact]
    public async Task Examples_GetById_ReturnsCorrectExample()
    {
        // Arrange
        var exampleEntity = new ExampleEntity();

        var dbContextFactory = GetComponent<ExampleDatabaseComponent>().DbContextFactory;

        await using (var context = dbContextFactory.NewDbContext())
        {
            context.Set<ExampleEntity>().Add(exampleEntity);

            await context.SaveChangesAsync();
        }

        var httpClient = GetComponent<ExampleApiComponent>().CreateClient();

        // Act
        var httpResponseMessage = await httpClient.GetAsync($"examples/{exampleEntity.Id}");

        // Assert
        httpResponseMessage.IsSuccessStatusCode.Should().BeTrue();

        var body = await httpResponseMessage.Content.ReadAsStringAsync();

        var result = JsonConvert.DeserializeObject<ExampleEntity>(body)!;

        result.Id.Should().Be(exampleEntity.Id);
    }
}

Parallel execution (Premium feature)

One of the best features of Accelergreat is the ability to have your integration tests run in parallel, gaining massive performance improvements on multi-threaded machines.

It's as easy as config change. In your accelergreat configuration, make sure to add your client id and client secret:

{
  "$schema": "https://cdn.accelergreat.net/configuration/3.0.0-beta.1/schema.json#",
  "License": {
    "ClientId": "YourClientId",
    "ClientSecret": "YourClientSecret"
  }
}

Given credentials are provided and authentication is successful, Accelergreat will automatically execute in parallel when the following criteria is met:

• More than 1 test collection is queued for execution.
• parallelizeTestCollections has not been set to false in your xunit.runner.json.
• maxParallelThreads has not been set to 1 in your xunit.runner.json.

By default, Accelergreat uses the max threads allowed from the number of logical processors on the machine. You can override this by setting the maxParallelThreads property in your xunit.runner.json configuration file.

Debugging in Visual Studio

Important When debugging tests in Visual Studio, do not click the stop button. Even if an exception occurs, click continue and let the test run through. If you click the stop button xunit will not run cleanup operations and dependencies will not be disposed of. This is especially important when debugging tests that use database dependencies.

Supported integrations

Entity Framework

• In-Memory
• Sqlite
• SQL Server
• PostgreSql

Application

• .NET Web API: dotnet6+

Upcoming integrations

Entity Framework

• MySql
• CosmosDB

Application

• Azure Functions
• AWS Lambda

Questions & Feedback

Please email mail@accelergreat.net for any questions or feedback you may have.