Precept 0.14.0

Assertions

await Assert.That(order.Total).ToBeEqualAsync(42.00m);

Every assertion is awaited, and it reads as the sentence its failure prints:

Expected order.Total to be equal to 42.00, but found 41.50.

The subject names itself from the expression the test wrote, so nothing has to be repeated in a message. Pass a name when the expression is not the point: Assert.That(total, "the basket total").

Why is every assertion awaited? An assertion over a value in hand completes at once. But the same sentence also covers an element that is not on the page yet, and a job that finishes eventually. The waiting lives inside the assertion instead of in a sleep in front of it, and the caller does not have to know which kind it wrote.

What ships#

Any value ToBeEqualAsync(x), ToBeSameAsAsync(x), ToBeNullAsync(), ToBeOneOfAsync(a, b), ToSatisfyAsync(predicate, "be …")
bool ToBeTrueAsync(), ToBeFalseAsync()
IComparable ToBeGreaterThanAsync(x), ToBeGreaterThanOrEqualAsync(x), ToBeLessThanAsync(x), ToBeLessThanOrEqualAsync(x), ToBeInRangeAsync(a, b)
string ToContainAsync(s), ToStartWithAsync(s), ToEndWithAsync(s), ToMatchAsync(pattern), ToBeEmptyAsync()
Collections ToContainAsync(item), ToHaveCountAsync(n), ToBeEmptyAsync(), ToOnlyContainAsync(predicate, "be …")
Actions ToThrowAsync<TException>() (returns the exception), ToCompleteAsync()

Modifiers go in front of the assertion:

await Assert.That(basket.Items).Not.ToBeEmptyAsync();
await Assert.That(total).Because("the promo code is 10% off").ToBeEqualAsync(90m);

Assert.MultipleAsync collects failures instead of stopping at the first, so one run reports every field that is wrong:

await Assert.MultipleAsync(async () =>
{
    await Assert.That(summary.Name).ToBeEqualAsync("Ada Lovelace");
    await Assert.That(summary.Email).ToBeEqualAsync("ada@example.com");
    await Assert.That(summary.Orders).ToHaveCountAsync(3);
});

Waiting for something to become true#

Assert.Eventually takes a function that gets the value, rather than the value itself. It calls the function again until the expectation holds or the timeout passes:

await Assert.Eventually(() => Rest.Get($"/jobs/{id}").SendAsync())
            .Within(TimeSpan.FromMinutes(2))
            .ToHaveJsonValueAsync("state", "Completed");

await Assert.Eventually(() => Db.ScalarAsync<long>("select count(*) from outbox where sent = 0"))
            .ToBeEqualAsync(0L);

Every assertion works with Eventually, because the waiting belongs to the subject, not to the expectation. A function that throws counts as "not there yet" and is retried. If the deadline passes, that exception becomes the failure's cause. The defaults are in precept.json:

{
  "Assertions": {
    "TimeoutMilliseconds": 5000,
    "PollIntervalMilliseconds": 100
  }
}

On a page#

Precept.Web maps Playwright's web-first assertions onto the same sentence. The retrying is Playwright's own, and Precept never polls on top of it, so these need no wait in front of them:

var page = await Browser.PageAsync();

await Assert.That(page).ToHaveTitleAsync(new Regex("Checkout"));
await Assert.That(page.GetByRole(AriaRole.Alert)).Not.ToBeVisibleAsync();
await Assert.That(page.GetByTestId("total"), "the basket total")
            .Within(TimeSpan.FromSeconds(10))
            .ToHaveTextAsync("£42.00");

Locator assertions: ToBeVisibleAsync, ToBeHiddenAsync, ToBeAttachedAsync, ToBeEnabledAsync, ToBeDisabledAsync, ToBeEditableAsync, ToBeCheckedAsync, ToBeFocusedAsync, ToBeEmptyAsync, ToBeInViewportAsync, ToHaveTextAsync, ToContainTextAsync, ToHaveValueAsync, ToHaveValuesAsync, ToHaveAttributeAsync, ToHaveClassAsync, ToContainClassAsync, ToHaveIdAsync, ToHaveCssAsync, ToHaveJsPropertyAsync, ToHaveCountAsync, ToHaveRoleAsync, ToHaveAccessibleNameAsync, ToHaveAccessibleDescriptionAsync, ToHaveAccessibleErrorMessageAsync and ToMatchAriaSnapshotAsync.

Page assertions: ToHaveUrlAsync, ToHaveTitleAsync and ToMatchAriaSnapshotAsync.

ToHaveTextAsync, ToContainTextAsync and ToHaveValuesAsync also take several values. The locator then has to resolve to one element per value, in that order. A list that grew an item fails rather than passing on the items that still match:

await Assert.That(page.GetByRole(AriaRole.Listitem)).ToHaveTextAsync("Espresso", "Cortado");

ToMatchAriaSnapshotAsync asserts a whole region's roles and names at once, in Playwright's YAML. It describes what the page means rather than how it is built:

await Assert.That(page.GetByRole(AriaRole.Navigation)).ToMatchAriaSnapshotAsync("""
    - list:
      - listitem:
        - link "Orders"
    """);

Anything not mirrored, such as an option Precept does not surface or an assertion Playwright adds later, goes through ToSatisfyAsync:

await Assert.That(page.Locator("main")).ToSatisfyAsync(
    "be half in the viewport",
    expect => expect.ToBeInViewportAsync(new() { Ratio = 0.5f }));

A failed web assertion keeps Playwright's call log, which says what the page looked like on each retry:

Expected the heading to have the text "Sign out", but found 'Sign in'.
Because the page has loaded.
Call log:
  - Expect "ToHaveTextAsync" with timeout 700ms
  - waiting for Locator("#heading")
    8 × locator resolved to <h1 id="heading">Sign in</h1>
      - unexpected value "Sign in"

The wait is Web:AssertionTimeoutMilliseconds (5 s by default). It is separate from Web:TimeoutMilliseconds, because an action usually waits far longer for an element than a check should. .Within(…) overrides it per assertion.

On a response#

Precept.Api adds ToHaveStatusAsync, ToBeSuccessfulAsync, ToHaveHeaderAsync, ToContainAsync, ToHaveJsonValueAsync and ToRespondWithinAsync. It also adds narrowing helpers that hand part of the response to the general assertions:

var response = await Rest.Get("/orders/42").SendAsync();

await Assert.That(response).ToBeSuccessfulAsync();
await Assert.That(response).JsonAt("customer.email").ToEndWithAsync("@example.com");
await Assert.That(response).Json<Order>().ToSatisfyAsync(o => o.Lines.Count == 2, "have two lines");

Every failure carries the request line and the body, because that is always the next question.

XML#

An API that speaks XML gets the same sentences. WithXmlBody writes a [DataContract] type with DataContractSerializer, Xml<T> reads one back, and XmlAt reads a single value by XPath: an element's text, an attribute's value, or the result of a function such as count():

var response = await Rest.Post("/policies/drafts")
    .WithXmlBody(new PolicyDraftRequest { ProductCode = "MOTOR-STD", CustomerId = "CUST-1001" })
    .SendAsync();

await Assert.That(response).ToHaveXmlValueAsync("/s:policy/s:status", "Draft");
await Assert.That(response).XmlAt("/s:policy/@number").ToStartWithAsync("POL-");
await Assert.That(response).Xml<Policy>().ToSatisfyAsync(p => p.Premium > 0, "carry a premium");

The s: prefix comes from Api:XmlNamespaces in precept.json. XPath has no default namespace, and a data contract's XML is always in one, so an unprefixed path such as /policy/status selects nothing in <policy xmlns="urn:sales">. Declare the prefix once and every path can use it:

{ "Api": { "XmlNamespaces": { "s": "urn:sales" } } }

Two things about the serializer decide whether the XML matches the service's schema, and both are set on the contract rather than in Precept:

  • [DataContract(Namespace = …)] replaces the serializer's default namespace of http://schemas.datacontract.org/2004/07/…, which no service expects.
  • [DataMember(Order = n)] fixes the element order, which is alphabetical otherwise. The serializer reads in that order too. An element that arrives out of place is skipped, and the property is left at its default with no error.

Both methods take a DataContractSerializerSettings for anything beyond that, passed through untouched. A schema that uses XML attributes is outside what a data contract can express. Send that body with WithBody(xml, "application/xml"), and read the answer with XmlAt, which handles attributes, or from Body.

Writing your own#

An assertion is an extension method on Subject<T> that hands an Expectation<T> to the engine. There is no registration and no base class, and no difference between one you write and one Precept ships:

using Precept.Assertions;

public static class InvoiceAssertions
{
    public static Task ToBeOverdueAsync(this Subject<Invoice> subject) =>
        subject.ExpectAsync(Expectation.For<Invoice>(
            "be overdue",                                                  // completes "Expected … to …"
            invoice => !invoice.Paid && invoice.DueDate < DateTime.UtcNow,
            invoice => $"an invoice due {invoice.DueDate:d} that was {(invoice.Paid ? "paid" : "unpaid")}"));
}
Expected invoice to be overdue, but found an invoice due 12/08/2026 that was unpaid.

That one method now supports everything the built-in assertions do. .Not inverts it, Assert.Eventually retries it, .Because and .Within reach it, and Assert.MultipleAsync collects it. All of that lives in the engine rather than in the assertion.

Two more pieces are there when a module needs them:

  • subject.Map(selector, name) narrows a subject to a part of itself, keeping every modifier and the re-reading. Assert.That(response).Status() is one line of Map, and it composes: Assert.Eventually(…).JsonAt("state").ToBeEqualAsync("Done") re-reads the whole response and re-selects the field on every attempt.
  • new Expectation<T>(description, evaluate) is the raw form, for a check that waits on its own or writes its own failure text. It sees AssertionContext.IsNegated and .Timeout and answers with AssertionOutcome.Satisfied or AssertionOutcome.Failed(actual, detail). This is how Precept.Web hands negation and the timeout down to Playwright's Expect() and keeps its call log.

For a one-off, ToSatisfyAsync(predicate, "be …") needs no method at all.

Precept 0.14.0 · MIT · © 2026

Esc