Peaceful.Canton.Localnet.Testing 0.7.3.1

Peaceful.Canton.Localnet.Testing

For the full consumer guide, see docs/public/integration-testing.md.

xUnit fixtures for Canton LocalNet integration tests. Sub-modules:

• EndpointDiscovery — env vars to URLs (JSON Ledger API, Keycloak token endpoint).
• OAuth2TokenProvider — client_credentials grant with in-memory cache + refresh.
• JsonLedgerAdminClient — thin HttpClient wrapper. Currently surfaces GET /v2/parties/participant-id.
• DarUploader — POST /v2/packages for one DAR or many; idempotent: a KNOWN_PACKAGE_VERSION 400 response is treated as success.
• PartyAllocator — POST /v2/parties with hint <consumer-prefix>-<instance-suffix> where the suffix is a 12-hex cryptographic random per fixture instance.
• UserBuilder — POST /v2/users followed by POST /v2/users/{id}/rights to grant CanActAs / CanReadAs.
• LocalnetFixture — composes the above into a single user-facing surface via Microsoft.Extensions.DependencyInjection and exposes convenience pass-throughs (UploadDarAsync, AllocatePartyAsync, CreateUserAsync, GetParticipantIdAsync). Validator(slot) returns a per-slot view exposing the same deep modules scoped to a single validator (handy for cross-validator scenarios); KnownSlots() returns the canonical slot set in stable order (sv-validator-1, a-validator-1, b-validator-1, c-validator-1, d-validator-1).

30-line example

await using var fixture = LocalnetFixture.FromEnvironment();

await fixture.UploadDarAsync("./dars/my-workflow-1.0.0.dar");

var party = await fixture.AllocatePartyAsync("globex");

await fixture.CreateUserAsync(
    userId: $"globex-user-{fixture.PartyAllocator.InstanceSuffix}",
    primaryParty: party.PartyId,
    actAs: new[] { party.PartyId });

Environment variables

The fixture reads these env vars (matching the compose stack ports in compose/modules/localnet/env/common.env):

The integration test (LocalNetIntegrationTests) self-skips when CANTON_LOCALNET_JSON_API_URL / CLIENT_ID / CLIENT_SECRET are not set, so unit tests run cleanly on a developer machine without make up.

These env vars are the fixture / test config layer — distinct from canton-localnet.yaml, which configures the CLI's stack-boot (canton-localnet up). The fixture connects to an already-running stack and needs per-slot URLs / credentials, so env vars are the discovery mechanism here.

Run

dotnet test --filter "Category!=Integration"             # unit tests only
dotnet test                                              # all (smoke skipped unless env set)
dotnet pack src/Peaceful.Canton.Localnet.Testing -c Release

Layout

csharp/
  Directory.Build.props          # net10.0, nullable, treat warnings as errors
  Directory.Packages.props       # central package versions
  NuGet.config                   # pins source to nuget.org with mapping
  coverage.settings.xml          # MTP code-coverage config shared with csharp-ci.yaml
  Peaceful.Canton.Localnet.Testing.sln
  src/Peaceful.Canton.Localnet.Testing/
  tests/Peaceful.Canton.Localnet.Testing.Tests/