TestingBot .NET SDK

The official .NET SDK for the TestingBot REST API. Manage tests, builds, app storage, tunnels, devices, screenshots, Codeless tests/suites, jobs, and team accounts from C#.

• Async all the way down, with CancellationToken support everywhere
• Thread-safe — construct one client and reuse it across your application
• Strongly typed models — no dynamic, no untyped dictionaries
• Zero third-party dependencies in the core package
• Resilient — automatic retries with exponential backoff and Retry-After support
• Optional dependency-injection package wiring up IHttpClientFactory
• Targets .NET 8 and .NET 9

Packages

Package	Purpose
TestingBot.Api	Core client and models (zero third-party dependencies)
TestingBot.Api.DependencyInjection	AddTestingBot() for IServiceCollection / IHttpClientFactory

Installation

dotnet add package TestingBot.Api
# optional, for ASP.NET Core / Worker apps:
dotnet add package TestingBot.Api.DependencyInjection

Authentication

Provide your API key and secret directly, or let the SDK resolve them (in order) from a ~/.testingbot file (key:secret), the TESTINGBOT_KEY/ TESTINGBOT_SECRET environment variables, or TB_KEY/TB_SECRET.

using TestingBot.Api;

var client = new TestingBotClient("YOUR_KEY", "YOUR_SECRET");
// or resolve from ~/.testingbot or environment variables:
var client = TestingBotClient.FromEnvironment();

Quick start

using TestingBot.Api;

using var client = new TestingBotClient("YOUR_KEY", "YOUR_SECRET");

// Who am I?
var user = await client.User.GetAsync();
Console.WriteLine($"{user.Email} — {user.Seconds} seconds remaining");

// A single test, by id or WebDriver session id
var test = await client.Tests.GetAsync("a1b2c3d4-...");
Console.WriteLine($"{test.Name}: {test.Success}");

// Mark a test passed and tag it
await client.Tests.UpdateAsync(test.SessionId!, new TestUpdate
{
    Success = true,
    StatusMessage = "All assertions passed",
    Build = "ci-1421",
    Groups = ["smoke", "checkout"],
});

Pagination

List endpoints return a TestingBotPage<T> (the items plus meta), or you can stream every item across all pages with ListAllAsync:

// One page at a time
var page = await client.Tests.ListAsync(new TestListOptions { Count = 50, Build = "ci-1421" });
Console.WriteLine($"{page.Count} of {page.Meta.Total}");

// Or iterate everything (pages fetched lazily)
await foreach (var t in client.Tests.ListAllAsync(new TestListOptions { Build = "ci-1421" }))
{
    Console.WriteLine($"{t.Id}: {t.Success}");
}

Uploading apps (storage)

Uploads are streamed (never fully buffered in memory), support progress reporting, and use a longer timeout than ordinary calls.

var progress = new Progress<long>(bytes => Console.WriteLine($"{bytes:N0} bytes sent"));
var app = await client.Storage.UploadAsync(new FileInfo("app.apk"), progress);
Console.WriteLine(app.AppUrl); // tb://<appkey> — pass as the `app` capability

// Replace the binary behind an app key without changing the tb:// URL:
await client.Storage.ReplaceAsync(app.AppKey!, new FileInfo("app-new.apk"));

Codeless tests and jobs

var run = await client.CodelessSuites.TriggerAsync(suiteId);
Job job = await client.Jobs.WaitForCompletionAsync(run.JobId, timeout: TimeSpan.FromMinutes(10));
Console.WriteLine(job.Success);

Error handling

Every failure derives from TestingBotException; catch a specific type to react to a failure mode:

try
{
    await client.Tunnels.StopAsync(tunnelId);
}
catch (TestingBotRateLimitException ex)
{
    await Task.Delay(ex.RetryAfter ?? TimeSpan.FromSeconds(30));
}
catch (TestingBotAuthenticationException)
{
    Console.Error.WriteLine("Check your API key and secret.");
}
catch (TestingBotValidationException ex)
{
    foreach (var error in ex.ValidationErrors)
    {
        Console.Error.WriteLine(error);
    }
}

Exception	HTTP status
TestingBotAuthenticationException	401
TestingBotPaymentRequiredException	402 (insufficient credits)
TestingBotForbiddenException	403 (read-only account / not admin)
TestingBotNotFoundException	404
TestingBotValidationException	400
TestingBotRateLimitException	429 (carries RetryAfter)
TestingBotApiException	other 4xx/5xx, transport failures
TestingBotConfigurationException	missing credentials / invalid options (no HTTP)

Dependency injection

using Microsoft.Extensions.DependencyInjection;

builder.Services.AddTestingBot(options =>
{
    options.ApiKey = builder.Configuration["TestingBot:ApiKey"];
    options.ApiSecret = builder.Configuration["TestingBot:ApiSecret"];
});

// or bind from configuration:
builder.Services.AddTestingBot(builder.Configuration.GetSection("TestingBot"));

Then inject ITestingBotClient anywhere. The client is registered as a singleton backed by IHttpClientFactory with the SDK's authentication and retry handlers.

Configuration

Option	Default	Description
BaseAddress	https://api.testingbot.com/v1/	Override for sandbox/private deployments
Timeout	100s	Per-request timeout for ordinary calls
UploadTimeout	30m	Timeout for storage uploads
MaxRetries	3	Retries for transient failures (429/5xx) on idempotent requests
RetryBaseDelay	1s	Base delay for exponential backoff
RespectRetryAfter	true	Honor the server's Retry-After header
DefaultPageSize	50	Page size used by ListAllAsync helpers

API coverage

Tests, Builds, Storage, Screenshots, Tunnels, Devices, Browsers, CodelessTests, CodelessSuites, Jobs, Team, User, Configuration, plus GetSharingAuthHash for building public share URLs.

Contributing & development

dotnet build
dotnet test
dotnet format --verify-no-changes

Integration tests run only when TESTINGBOT_KEY/TESTINGBOT_SECRET are set and are otherwise skipped.

License

MIT — see LICENSE.