Skip to content

README.md

Latest commit

 

History

History
90 lines (63 loc) · 3.79 KB

README.md

File metadata and controls

90 lines (63 loc) · 3.79 KB

observer-dotnet

Minimal .NET-facing provider micro-library for Observer.

If you are new to this surface, start with HOWTO.md before reading the individual snippets and starters.

This aims at the same DX bar as the C, Go, Rust, TypeScript, and Python libraries:

  • authors write Spec.Describe(...), Spec.Test(...), Spec.It(...), and Spec.Expect(...)
  • default identity is derived deterministically from explicit suite path plus test title
  • optional Spec.Id(...) provides a refactor-stable override when needed
  • observation is bounded and opt-in through ctx.Observe().*
  • direct host and embedded observe dispatch are owned by the library

The common path stays human-first. The deterministic boundary stays explicit.

Files

  • HOWTO.md: detailed user manual covering authoring, determinism, host transport, inventory derivation, and end-to-end workflow
  • Observer.Dotnet.csproj: installable package metadata for the standalone .NET library
  • src/Observer.cs: public API
  • tests/Observer.Dotnet.SelfTest/: self-test coverage for the .NET SDK
  • examples/ExampleSmoke/: tiny collection and execution example
  • examples/HostExample/: tiny direct list and run host example
  • examples/HostEmbedExample/: own-main style observe namespace example
  • ../../examples/dotnet-consumer/: standalone consumer-style example outside the SDK subtree
  • starter/: runnable project-shaped example with .NET build, provider host build, inventory derivation, suite run, and snapshot verification
  • starter-embedded/: runnable app-shaped example where the application keeps Main() and routes observe ... through its own CLI
  • starter-failure/: runnable failing companion showing the same provider flow with one intentionally failing exported test

If you want the full end-to-end workflow rather than isolated snippets, start with starter/, then read starter-embedded/, and then compare those with starter-failure/.

Minimal Shape

using Observer.Dotnet;

var tests = Spec.CollectTests(() =>
{
    Spec.Describe("database", () =>
    {
        Spec.Test("access to the database", ctx =>
        {
            ctx.Stdout("ok\n");
            Spec.Expect(true).ToBeTruthy();
        });
    });
});

When Spec.Id(...) is omitted, Observer derives a deterministic identity from suite path, test title, and duplicate occurrence order.

Install

Inside this repo, the examples use a project reference to Observer.Dotnet.csproj.

For a normal .NET project, the natural install paths are:

  • dotnet add reference path/to/Observer.Dotnet.csproj
  • dotnet pack lib/dotnet/Observer.Dotnet.csproj and then consume the resulting package

The package multi-targets net8.0 and net10.0. The examples and starters target net8.0 so the default path stays mainstream.

If you want the closest thing in this repo to a normal external consumer, start with ../../examples/dotnet-consumer/.

Test

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

Smoke Example

dotnet run --project lib/dotnet/examples/ExampleSmoke/ExampleSmoke.csproj

Host Example

dotnet run --project lib/dotnet/examples/HostExample/HostExample.csproj -- list
dotnet run --project lib/dotnet/examples/HostExample/HostExample.csproj -- observe --target pkg::smoke --timeout-ms 1000
dotnet run --project lib/dotnet/examples/HostExample/HostExample.csproj -- run --target pkg::fail --timeout-ms 1000

The library owns the standard provider host transport for .NET too. A direct host can stay nearly trivial through Spec.HostMain(...).

Own Main Integration

If a project already owns its CLI, the library can also serve an embedded observe namespace. The runnable example lives in examples/HostEmbedExample/, and the full app-shaped workflow lives in starter-embedded/.