ApiTestFramework 0.1.2

ApiTestFramework

Lightweight, pluggable test framework utilities for exercising real HTTP APIs in .NET 8.0 solutions. It ships an ApiClient (with JWT support), data-source readers, logging abstractions, and optional reporting hooks so you can focus on authoring clear, reliable API tests.

Install (NuGet)

Add the package to any test or integration project (xUnit, NUnit, MSTest, console harness, etc.). Pin for reproducibility:

dotnet add package ApiTestFramework --version 0.1.2

Or pull the latest available:

dotnet add package ApiTestFramework

Quick Start

using ApiClient; // Namespace of the ApiClient in the package

var baseUrl = "https://api.example.com";       // Your API root
var token   = "eyJhbGci...";                    // JWT or bearer token

var client = new ApiClient.ApiClient(baseUrl, token);
var user   = await client.GetAsync<dynamic>("/users/1");
Console.WriteLine(user);

Key async methods:

• GetAsync<T>(string path)
• PostAsync<T>(string path, object body)
• (Extend similarly for PUT/DELETE if required in your project)

Real API Integration Test Example (xUnit)

Integration tests against a live server are powerful but slow & environment-dependent. Keep them opt-in by skipping them unless required. Example below uses environment variables so CI/secrets are not hard-coded:

using System;
using System.Threading.Tasks;
using Xunit;
using ApiClient;

namespace ApiTests
{
    // Disabled by default; enable by setting TEST_API_BASE_URL and TEST_API_TOKEN or removing Skip.
    public class ApiClientRealIntegrationTests
    {
        private const string EnvBaseUrl = "TEST_API_BASE_URL";
        private const string EnvToken   = "TEST_API_TOKEN";

        [Fact(Skip = "Integration test - enable by setting TEST_API_BASE_URL and TEST_API_TOKEN or removing Skip")]
        public async Task GetAsync_Integration_FetchesSingleUser_RealServer()
        {
            var baseUrl = Environment.GetEnvironmentVariable(EnvBaseUrl);
            var token   = Environment.GetEnvironmentVariable(EnvToken);
            if (string.IsNullOrEmpty(baseUrl) || string.IsNullOrEmpty(token))
                throw new InvalidOperationException($"Integration test requires environment variables {EnvBaseUrl} and {EnvToken} to be set.");

            var apiClient = new ApiClient.ApiClient(baseUrl, token);
            var user = await apiClient.GetAsync<dynamic>("/users/1");
            Assert.NotNull(user);
        }

        [Fact(Skip = "Integration test - enable by setting TEST_API_BASE_URL and TEST_API_TOKEN or removing Skip")]
        public async Task PostAsync_Integration_CreatesUser_RealServer()
        {
            var baseUrl = Environment.GetEnvironmentVariable(EnvBaseUrl);
            var token   = Environment.GetEnvironmentVariable(EnvToken);
            if (string.IsNullOrEmpty(baseUrl) || string.IsNullOrEmpty(token))
                throw new InvalidOperationException($"Integration test requires environment variables {EnvBaseUrl} and {EnvToken} to be set.");

            var apiClient = new ApiClient.ApiClient(baseUrl, token);
            var payload = new { name = "Integration Test User", email = "itest+user@example.com" };
            var created = await apiClient.PostAsync<dynamic>("/users", payload);
            Assert.NotNull(created);
        }
    }
}

Enabling Integration Tests (Windows PowerShell)

$env:TEST_API_BASE_URL = "https://api.yourserver.com"
$env:TEST_API_TOKEN    = "your-jwt-or-bearer-token"
dotnet test

For a one-off invocation:

TEST_API_BASE_URL="https://api.yourserver.com"; TEST_API_TOKEN="token"; dotnet test

Guidelines

• Keep unit tests fast & isolated; only mark a few critical real-path scenarios as integration.
• Fail fast if env vars absent (as shown) for clear developer feedback.
• Consider separate CI job/stage for live API tests.

Package Contents Overview

Logging

Use FileTestLogger for lightweight run diagnostics; plug in AppInsightsLogger when instrumentation key & configuration are available. Wrap logging via ITestLogger for dependency injection and test isolation.

Data-Driven Tests

Readers expose simple APIs to fetch structured rows that can feed [Theory] test data. Example pattern:

var csv = new CsvDataReader();
var rows = csv.Read<MyRow>("TestData/users.csv");
foreach (var r in rows)
    Assert.False(string.IsNullOrWhiteSpace(r.Email));

(Adjust generics and schema mapping per implementation.)

Error Handling Strategy

Non-success HTTP responses surface as HttpRequestException including status/body for quick diagnosis. Expect/Assert error flows by capturing the exception and inspecting StatusCode or serialized problem details.

Publishing (dotnet pack & push)

Create a package:

dotnet pack .\ApiTestFramework\ApiTestFramework.csproj -c Release -o .\nupkg

Push to feed:

dotnet nuget push .\nupkg\ApiTestFramework.*.nupkg --source "<FeedUrl>" --api-key "<API_KEY>"

Include symbols (.snupkg) for better debugging in consuming solutions.

Optional Reporting (Allure)

Framework keeps reporting dependencies out to remain lean. If you need rich step/result reports, add Allure packages in the consuming test project and wrap lifecycle events. (Previous extended example retained in version history.)

Roadmap Ideas

• Polly-based retries / circuit breaker for transient faults.
• PATCH / DELETE convenience methods.
• Token auto-refresh & expiry buffer in JwtAuthenticator.
• Extended structured logging (correlation IDs, timing).
• Advanced data-binding helpers for complex CSV schemas.

Troubleshooting

• 401/403: Verify the token env var is set and unexpired.
• Serialization issues: Confirm JSON casing settings; payload might be a JsonElement—inspect properties directly.
• Timeouts: Increase client timeout or check network connectivity.
• Empty data rows: Validate file path & ensure build CopyToOutputDirectory if needed.

License

MIT (adjust as organizational policy requires).

Contributing

1. Fork & create feature branch.
2. Add/adjust code (keep changes focused & small).
3. Include XML doc comments for public members.
4. Update this README if new public features ship.
5. Open PR referencing issue or enhancement request.

Versioning

Semantic versioning (MAJOR.MINOR.PATCH). Breaking API changes increment MAJOR; additive backwards-compatible features increment MINOR; fixes/security patches increment PATCH.

At a Glance

Changelog

• 0.1.2: Updated README content and version; added changelog.
• 0.1.1: Refined README, installation guidance, integration test examples.
• 0.1.0: Initial release with core client, readers, logging abstractions.

Happy testing!