Skip to content

HOWTO.md

Latest commit

 

History

History
152 lines (104 loc) · 4.42 KB

HOWTO.md

File metadata and controls

152 lines (104 loc) · 4.42 KB

Observer .NET HOWTO

This manual explains how to use Observer's .NET-facing provider library.

It is written for projects that want C#-native test authoring while still exposing deterministic provider contracts to Observer.

Quick Start: First 5 Commands

If you want the fastest path to the .NET provider model, start in starter/ and run:

make list
make inventory
cat tests.inv
make run
make verify

That shows the whole path in order:

  • raw provider host discovery
  • derived canonical inventory
  • the exact execution contract Observer will run against
  • a real suite execution with the human console
  • hash and JSONL verification against checked-in expected artifacts

If your application already owns its CLI, use starter-embedded/ instead. That path keeps normal application behavior outside an explicit observe routing point.

If you want a normal consumer-shaped .NET app rather than an SDK-local example, see ../../examples/dotnet-consumer/.

1. What This Library Is

This library is the .NET-facing micro-SDK for Observer's provider contract.

It lets .NET authors write tests with a human-first surface:

  • Spec.Describe(...)
  • Spec.Test(...)
  • Spec.It(...)
  • Spec.Expect(...)
  • ctx.Observe().Metric/Vector/Tag

Underneath that surface, Observer still enforces its own rules:

  • deterministic collection
  • explicit canonical identity
  • duplicate validation
  • bounded observation
  • standard provider host transport for list, run, and observe

2. Smallest Useful Shape

using Observer.Dotnet;

var tests = Spec.CollectTests(() =>
{
    Spec.Describe("math", () =>
    {
        Spec.Test("adds two numbers", ctx =>
        {
            ctx.Stdout("ok\n");
            Spec.Expect(2 + 3).ToBe(5);
        });
    });
});

3. Deterministic Identity

If Spec.Id(...) is omitted, Observer derives the canonical identity from suite path plus test title.

If a test needs a refactor-stable identity, give it an explicit Spec.Id(...).

4. Author Context

Each test receives one context object.

The common author operations are:

  • ctx.Stdout(...)
  • ctx.Stderr(...)
  • ctx.Fail(...)
  • ctx.Observe()

5. Expectations

The first-cut matcher surface includes:

  • Spec.Expect(value).ToBe(expected)
  • Spec.Expect(value).ToEqual(expected)
  • Spec.Expect(value).ToContain(expected)
  • Spec.Expect(value).ToMatch(pattern)
  • Spec.Expect(value).ToBeTruthy()
  • Spec.Expect(value).ToBeFalsy()
  • Spec.Expect(value).Not.ToBe(...)

6. Provider Host Transport

The .NET library owns the standard provider host transport.

That means the host surface is:

  • list
  • run --target <target> --timeout-ms <u32>
  • observe --target <target> --timeout-ms <u32>

The public SDK entrypoints are:

  • Spec.HostMain(...)
  • Spec.HostDispatch(...)
  • Spec.HostDispatchEmbedded(...)

7. Embedded Observe Integration

If a .NET application already owns Main(), it can expose an embedded observe namespace. See examples/HostEmbedExample/ and starter-embedded/.

8. Starter Workflow

The runnable starter in starter/ shows the real adoption path:

  1. write ordinary .NET code under test
  2. author Observer tests in C# with Spec.*
  3. expose those tests through a small provider host executable
  4. derive canonical inventory through observer derive-inventory
  5. run a suite against that inventory
  6. verify canonical hashes and report output against checked-in snapshots

The failing companion in starter-failure/ keeps the same flow but preserves one intentional failure so the deterministic failure report path stays easy to inspect.

9. Embedded Starter Workflow

The runnable starter in starter-embedded/ shows the application-owned CLI path:

  1. keep normal application behavior in Main()
  2. route observe ... through Spec.HostDispatchEmbedded(...)
  3. configure Observer with args = ["observe"]
  4. derive canonical inventory through observer derive-inventory
  5. run the same suite shape against the embedded provider boundary
  6. verify canonical hashes and report output against checked-in snapshots

10. Library Self-Tests And Packaging

The SDK carries a self-test project:

dotnet run --project lib/dotnet/tests/Observer.Dotnet.SelfTest/Observer.Dotnet.SelfTest.csproj

The install story is the package metadata in Observer.Dotnet.csproj, which supports dotnet pack when needed.

For local adoption inside a .NET solution, dotnet add reference path/to/Observer.Dotnet.csproj is the shortest path.