Canton.Ledger.Testing 0.6.0

Canton.Ledger.Testing

In-memory test doubles and event/result builders for unit-testing business logic against the Canton Ledger API client surfaces without a live participant and without a mocking framework. Part of the Canton .NET SDK.

FakeLedgerClient implements the neutral Canton participant surface Canton.Ledger.Abstractions.ICantonLedgerClient (and therefore the transport-neutral Daml.Ledger.Abstractions.ILedgerClient it extends). FakeAdminClient, FakeTokenProvider and FakePqsClient implement the equally neutral Canton.Ledger.Abstractions.IAdminClient, Canton.Ledger.Abstractions.ITokenProvider and Canton.Ledger.Abstractions.IPqsClient. Every fake therefore stands in for a contract declared in one neutral package, and this package depends only on Canton.Ledger.Abstractions/Daml.Ledger.Abstractions/Daml.Runtime — no transport, no Canton.Ledger.Kernel, no PostgreSQL driver.

Installation

dotnet add package Canton.Ledger.Testing --version 0.6.0

Every fake replays canned data staged ahead of time — none of them is a semantic ledger/PQS simulator (no contract-key uniqueness or consuming-choice archival). FakePqsClient does evaluate the PqsFilter it is given against the staged contracts, with the semantics of the SQL a live PQS runs. The one exception is FakeLedgerClient's ledger end: it starts at the offset staged through WithLedgerEnd and advances by one offset per committed write, so a test can read the end, write, read it again, and get a bounded (fromOffset, toOffset] window that actually contains the write. The Canton participant surface (ICantonLedgerClient — fire-and-forget submission, the completion stream, synchronizer/version discovery, offset/id point reads, tree-shaped submission, traffic-cost estimation, interactive submission and package preference) lives directly on FakeLedgerClient: seed completion events, connected synchronizers, the Ledger API version, point-read transactions, transaction trees, the traffic-cost estimate, the prepared and executed interactive submissions and the preferred packages the same way, so tests swap Fake ⇆ REST ⇆ gRPC behind one interface. SubmitAsync/SubmitReassignmentAsync echo the submission's command id (minting one when omitted).

Key types

Usage

Stage the active-contract snapshot your business logic will read, keyed by Daml type, then drive it through the fake:

using Canton.Ledger.Testing;
using Daml.Ledger.Abstractions;
using Daml.Runtime;
using Daml.Runtime.Contracts;
using Daml.Runtime.Data;

var owner = new Party("bob");
var asset = new DemoAsset(new Party("issuer"), owner, "GOLD", 42m);

ILedgerClient client = FakeLedgerClient.Create()
    .WithActiveContracts(
        LedgerEvents.Created(
            new ContractId<DemoAsset>("cid1"),
            asset,
            key: null,
            LedgerOffset.At(1),
            (SynchronizerId)"sync1",
            [owner]),
        LedgerEvents.Checkpoint<DemoAsset>(LedgerOffset.At(2)))
    .Build();

// SubscribeActiveAsync<DemoAsset> now replays the staged entries:
await foreach (var entry in client.SubscribeActiveAsync<DemoAsset>(owner))
{
    // ... exercise the code under test ...
}

// A member you never staged fails loudly instead of returning empty/null:
// client.TryExerciseAsync<string>(...)  ->  NotSupportedException("...WithExerciseResult<String>...")

Every unconfigured member and every unstaged Daml type throws a NotSupportedException whose message names the builder call needed to stage it, so a test never silently exercises unconfigured behaviour.

Seed the completion stream to drive fire-and-forget submission logic (SubmitAsync then observe the completion), using the neutral CommandAccepted/CommandRejected/Checkpoint events:

using Canton.Ledger.Abstractions;
using Canton.Ledger.Testing;
using Daml.Runtime;
using Daml.Runtime.Commands;
using Daml.Runtime.Data;

var owner = new Party("bob");
var completion = new Completion(
    new CommandId("cmd-1"), Offset: LedgerOffset.At(1), ActAs: [owner],
    new SynchronizerTime("sync1", DateTimeOffset.UtcNow),
    SubmissionId: null, UserId: null, DeduplicationPeriod: null,
    PaidTrafficCost: 0, TraceContext: null);

ICantonLedgerClient client = FakeLedgerClient.Create()
    .WithCompletionEvents(
        new CompletionStreamEvent.Checkpoint(LedgerOffset.Begin),
        new CompletionStreamEvent.CommandAccepted(completion, "update-1"))
    .Build();

await foreach (var completionEvent in client.CompletionStreamAsync(owner))
{
    // ... assert your code correlates the accepted completion by command id ...
}

Seed the submit-and-wait write path — the command shape every generated choice helper submits through — with the ExerciseOutcome<TransactionResult> your code under test should observe. TrySubmitAndWaitForTransactionAsync (both overloads) replies with the staged outcome for every submission; stage a success or a failure to drive either branch:

using Canton.Ledger.Testing;
using Daml.Ledger.Abstractions;
using Daml.Runtime;
using Daml.Runtime.Commands;
using Daml.Runtime.Contracts;
using Daml.Runtime.Data;
using Daml.Runtime.Outcomes;

ILedgerClient happy = FakeLedgerClient.Create()
    .WithSubmissionOutcome(LedgerOutcomes.One(LedgerResults.Transaction(
        "update-1",
        LedgerOffset.At(5),
        [
            new CreatedContract(
                "event-1",
                "cid1",
                DemoAsset.TemplateId,
                DamlRecord.Create(),
                WitnessParties: [],
                Signatories: [],
                Observers: []),
        ],
        archivedContractIds: [],
        (CommandId)"cmd-1")))
    .Build();

ILedgerClient failing = FakeLedgerClient.Create()
    .WithSubmissionOutcome(LedgerOutcomes.DamlError<TransactionResult>(
        DamlErrorCategory.InvalidGivenCurrentSystemStateOther,
        "UNHANDLED_EXCEPTION", "assertion failed", new Dictionary<string, string>()))
    .Build();

Stage an admin client the same way:

using Canton.Ledger.Abstractions;
using Canton.Ledger.Testing;
using Daml.Runtime.Data;

IAdminClient admin = FakeAdminClient.Create()
    .WithParticipantId("participant1")
    .WithUser(new UserDetails("alice", new Party("alice::1220")))
    .Build();

var participantId = await admin.GetParticipantIdAsync();
var alice = await admin.GetUserAsync("alice"); // staged UserDetails
var bob = await admin.GetUserAsync("bob");     // null — never staged, not an error

Stage a PQS client's query results per Daml type:

using Canton.Ledger.Abstractions;
using Canton.Ledger.Testing;
using Daml.Runtime.Contracts;

IPqsClient pqs = FakePqsClient.Create()
    .WithQueryResults(new Contract<Holding>(new ContractId<Holding>("cid1"), holding))
    .Build();

var holdings = await pqs.QueryAsync<Holding>();

And a token provider for either the happy path or an auth-failure path:

using Canton.Ledger.Abstractions;
using Canton.Ledger.Testing;

ITokenProvider ok = FakeTokenProvider.WithToken("test-bearer-token");
ITokenProvider failing = FakeTokenProvider.WithFailure(new InvalidOperationException("token endpoint unreachable"));

Stage a failed throwing call to test your failure handling. Both transports report a failed call as a LedgerOperationException, so one staged failure covers either; build it with the constructor that takes a TransportStatus and a CommitState when the test branches on them:

using Canton.Ledger.Testing;
using Daml.Ledger.Abstractions;
using Daml.Runtime.Outcomes;

var noAnswer = new LedgerOperationException(
    "read got no answer",
    new TransportStatus.NoResponse(),
    CommitState.NotCommitted,
    DamlErrorCategory.TransientServerFailure,
    errorId: null,
    metadata: null,
    innerException: new TimeoutException("no response"));

ILedgerClient failing = FakeLedgerClient.Create()
    .WithThrowingCallFailure(noAnswer)
    .Build();

var act = () => failing.GetLedgerEndAsync(); // throws noAnswer from its task

Zero mocking-framework dependency

None of the fakes in this package pull in Moq / NSubstitute, so it composes with any (or no) mocking framework in your own test project. Every fake — FakeLedgerClient, FakeAdminClient, FakeTokenProvider and FakePqsClient — depends only on Canton.Ledger.Abstractions, Daml.Ledger.Abstractions, and Daml.Runtime.