ag-ui: Skill for Claude Code

AG-UI .NET Integration Tests

End-to-end tests for the AG-UI .NET SDK that post RunAgentInput, stream events over the wire (SSE or protobuf), and assert behavior through the AGUIChatClient (IChatClient) abstraction.

Orientation

The canonical project layout, endpoint pattern, and naming live in sdks/dotnet/AGENTS.md (project layout + endpoint pattern) and sdks/dotnet/docs/architecture.md (the server/client pipeline). Read those first; this skill covers only the integration-test mechanics on top of them.

One durable gotcha: the test project folder and csproj are named tests/AGUI.Hosting.AspNetCore.IntegrationTests/ (kept after the server package was renamed to AGUI.Server), but all types live in namespace AGUI.Server.IntegrationTests. The ASP.NET hosting glue (AddAGUI, the negotiating endpoint, AGUIResults) lives in samples/AGUI.Samples.Shared, and the protobuf formatter comes from AGUI.Protobuf.

Project Layout

tests/AGUI.Hosting.AspNetCore.IntegrationTests/   # namespace AGUI.Server.IntegrationTests
├── Infrastructure/
│   ├── IntegrationTestBase.cs          # Two-tier base: generic <TEntryPoint> + non-generic (uses Program). Emit helpers, CollectUpdates, CreateClient(handler[, TransportFormat]), VerifyCaptures (8 capture points), recording load/save, id scrubbing.
│   ├── TransportFormat.cs              # enum { Json, Protobuf } — selects the wire encoding the test client negotiates
│   ├── DelegatingStreamingChatClient.cs # Func-based IChatClient for inline server behavior
│   ├── CapturingChatClient.cs          # IChatClient decorator that records server-side calls (ServerCallCapture)
│   ├── CapturingAGUITransport.cs       # IAGUITransport decorator that records client-side turns (TurnCapture)
│   ├── ServerCallCapture.cs            # RunAgentInput + ChatMessage[] + ChatOptions + ChatResponseUpdate[] per server call
│   ├── TurnCapture.cs                  # RunAgentInput + BaseEvent[] per client-side turn
│   ├── ChatResponseUpdateCaptureConverter.cs # JsonConverter that renders ChatResponseUpdate (+RawRepresentation) for snapshots
│   ├── AGUIEndpointExtensions.cs       # Test-local MapAGUI: ToChatRequestContext + AsAGUIEventStreamAsync, returns AGUIResults.Events (negotiating)
│   ├── AGUIServerSentEventsResult.cs   # Legacy SSE-only IResult (still present; the live endpoint uses AGUIResults instead)
│   ├── AGUICapabilitiesEndpointRouteBuilderExtensions.cs # Test-only AgentCapabilities publisher (the SDK ships no capabilities endpoint; the spec doesn't define one)
│   ├── Program.cs                      # Minimal host: AddAGUI() + register ProtobufEventStreamFormatter + DelegatingStreamingChatClient + MapAGUI("/agui")
│   └── VerifyConfig.cs                 # ModuleInitializer for Verify settings (DontScrubDateTimes, DiffRunner disabled)
├── RunLifecycleIntegrationTest.cs      # Run lifecycle events            [Theory Json/Protobuf]
├── TextStreamingIntegrationTest.cs     # Text streaming + multi-turn     [Theory Json/Protobuf]
├── ToolCallIntegrationTest.cs          # Tool call events                [Theory + one Json-only ToolCallResult fact]
├── ClientToolIntegrationTest.cs        # Client (frontend) tools          [Theory Json/Protobuf]
├── MixedToolInvocationIntegrationTest.cs # Mixed server+client tool batches (approval-flow) [Json-only, has Verify baselines]
├── FrontendToolReinvocationTest.cs     # Frontend tool re-invocation      [Json-only]
├── StateManagementIntegrationTest.cs   # State snapshot/delta             [Theory Json/Protobuf]
├── ReasoningIntegrationTest.cs         # Thinking/reasoning events        [Json-only]
├── ActivityIntegrationTest.cs          # Activity snapshot/delta          [Json-only]
├── CustomAndRawEventIntegrationTest.cs # Custom/raw events                [Theory Json/Protobuf]
├── RawRepresentationFactoryIntegrationTest.cs # Custom RawRepresentation factory [Theory Json/Protobuf]
├── CapabilitiesEndpointIntegrationTest.cs # Capabilities endpoint (exercises the test-local helper) [Json-only]
├── TransportEquivalenceIntegrationTest.cs # Asserts Json and Protobuf decode to identical ChatResponseUpdate sequences
├── AGUIResultsTest.cs                  # Accept-header negotiation (proto vs SSE vs 406) for AGUIResults.Events
├── Samples/GettingStarted/
│   ├── StepNN_XyzTest.cs               # Replay/snapshot test per sample (Step01..Step12)
│   ├── fixtures/{Sample}/*.recording.json   # Recorded List<List<ChatResponseUpdate>> (one list per turn)
│   └── baselines/{Sample}/*.verified.json   # Verify snapshots, one file per capture point (see below)
└── AGUI.Hosting.AspNetCore.IntegrationTests.csproj  # references AGUI.Client, AGUI.Protobuf, AGUI.Samples.Shared + every Step01..Step12 Client/Server