Accelergreat xunit testing tools. Accelergreat is an integration testing package that helps to simplify and speed up the writing of integration tests, as well as taking away the challenging task of managing external dependencies.
Write and execute efficient and high-performance integration tests with ease. Accelergreat 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.
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.
NuGet Packages
Accelergreat has a range of nuget packages for different feature sets:
Referenced by all other Accelergreat packages. You can also reference this package to make your own custom Accelergreat components.
Accelergreat.EntityFramework
Core Entity Framework package referenced by Accelergreat's Entity Framework packages.
Test framework packages
The test framework packages contain Accelergreat's test framework specific code. All other packages can be used interchangeably with each test framework package.
Accelergreat supports different database providers with the following entity framework packages. Accelergreat fully manages databse creation, reset between tests and cleanup at the end of the test run.
Accelergreat keeps up-to date with dotnet releases and each major version will support all currently in-support versions of dotnet at the time of release.
Accelergreat will not introduce amy breaking public API changes for minor and patch versions.
Getting started (xUnit)
Getting startes is easy, whether you are starting a new test project, or want to migrate an existing one.
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.
Accelergreat offers a range of pre-built components that can be extended for your specific needs. Or, you can build your own components by implementing the IAccelergreatComponent interface.
To further understand components beyond what the getting started guide explains, the different components Accelergreat offers and to understand how to build your own components. See the dedicated guide on components.
Configure the environment
Configure the environment by registering components in a startup class that implements the IAccelergreatStartup interface. Just like how you setup dependency injection for your application, Accelergreat uses dependency injection for environment and component resolution for your tests.
Write your tests! 🚀
Detailed steps (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.
Use case example: Database (Entity Framework SQL Server) + Web API integration test
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.
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:
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 an API 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 an API program class
With the recent introduction of using the program.cs file to replace the startup class, 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:
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);
}
}
Create a Startup class in your test project that implements IAccelergreatStartup.
we need to register our components. In the Configure implementation, call builder.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 ExampleTestProject.Components;
namespace ExampleTestProject;
public class Startup : IAccelergreatStartup
{
public void Configure(IAccelergreatBuilder builder)
{
builder.AddAccelergreatComponent<ExampleDatabaseComponent>();
builder.AddAccelergreatComponent<ExampleApiComponent>();
}
}
4. 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:
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);
}
}
Extensibility
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.
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:
The following configuration example shows how a premium developer has set their client ID and client secret, the developer is using the SQL Server Entity Framework component, the developer needs this to work slightly differently in their development and CI environments.
In the development environment, the developer wants to run their application in memory to be able to make use of Visual Studio debugging tools, and also make use of faster database reset speed by using the Transactions reset strategy.
In the CI environment, the developer wants to run their tests against the docker container that will be deployed to the hosted environments. In this case, the developer is using IL-trimming in the dotnet publish step of their Dockerfile.
On their local machine, the developer would set the ACCELERGREAT_ENVIRONMENT environment variable with value development, in the CI environment, the value would be CI.
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:
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.
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.
Database transactions
Resetting a databse between tests takes time. By default, Accelergreat uses the SnapshotRollback reset strategy that creates a snapshot of the database before the tests run, and performs a rollback on the database between each test.
The time it takes to reset a database will greatly impact how long it takes the entire test suite to run.
With the premium Transactions reset strategy, Accelergreat performs magic transaction management and all of your test database changes are made within a single transaction.
If your application uses transactions that is covered by your tests, you can enable TransactionOveriding and Accelergreat will do even more magic behind the scenes to nest your transactions within Accelergreats transaction.
This paired with the Parallel execution feature will let your tests 'make the jump to light speed' - Han Solo.
Licensing / Pricing
Accelergreat is free to use.
A paid subscription is available for those that want to use premium features.
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.
