Canton.Ledger.Testing 0.7.1

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.7.1

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).

FakeLedgerClient.Submissions lists every write the client was handed, one RecordedSubmission per call, in call order. A RecordedSubmission.Commands holds the command submission as the client puts it on the wire (the submitter's ActAs/ReadAs applied, the effective command id, the workflow id and the command; TryCreateAsync and TryExerciseAsync appear as the single-command submission they stand for), a RecordedSubmission.Reassignment holds a reassignment submission, and a RecordedSubmission.Execution holds the signed submission handed to ExecuteSubmissionAsync, ExecuteSubmissionAndWaitAsync or ExecuteSubmissionAndWaitForTransactionAsync. Select a kind with Submissions.OfType<RecordedSubmission.Commands>() and assert on your code's parties, payload, choice arguments and sequence of writes. EstimateTrafficCostAsync submits nothing and is not recorded.

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(
        CompletionEvents.Checkpoint(LedgerOffset.Begin),
        CompletionEvents.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: [])
            {
                PackageName = DemoAsset.PackageName,
            },
        ],
        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.

Excluding the package from your own code coverage

This package is test support, not code under test. When its PDB resolves next to the DLL, for example in a build packed on your own machine, a coverage tool counts its lines in your report. Exclude the module by path. With Microsoft.Testing.Extensions.CodeCoverage, put the exclusion in your coverage settings file:

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <CodeCoverage>
    <ModulePaths>
      <Exclude>
        <ModulePath>.*Canton\.Ledger\.Testing\.dll$</ModulePath>
      </Exclude>
    </ModulePaths>
  </CodeCoverage>
</Configuration>

Save it as coverage.settings.xml and pass it with --coverage-settings coverage.settings.xml. If you already have a settings file, add the ModulePath line to its existing ModulePaths Exclude list. With coverlet, use its own filter instead: Exclude set to [Canton.Ledger.Testing]*.