Kronikol

Automatically generates rich interactive HTML reports with PlantUML sequence, activity and component diagrams, with timeline visualizations from your integration/component test HTTP traffic (real or faked) and telemetry.

Tracks interactions between your test caller, your Service Under Test (SUT), and its dependencies — including HTTP calls, Azure Cosmos DB operations, SQL queries (via EF Core), Redis commands, events/messages, and arbitrary method calls — then converts them into sequence diagrams embedded in searchable HTML reports and YAML specification files. Method flow within the SUT itself is turned into activity diagrams. And the combination is turned into flame diagrams. All the flows combined are turned into a C4 Component Diagram for your service. A Scenario Timeline diagram allows you to visually compare the execution time of your services.

Input data sets (eg InlineData/MemberData/ClassData for xUnit, and equivalents in NUnit, TUnit & ReqNRoll & LightBDD) are automatically turned into dynamic clickable tables showing you the correct diagrams for each set of inputs. Data is all collapsible, truncatable and toggleable at view time, allowing you to see from higher level to lower level at the click of a button. Also contains features for tracking your assertions from FluentAssertions/AwesomeAssertions/TUnit assertions and displaying them in the reports in plain english.

Example Output ↑

This is just a very simple static example, for a full, rich, interactive example, see the generated BreakFastProvider diagrams in the BreakFastProvider project.

Each test that uses tracked dependencies automatically produces a sequence diagram (with matching PlantUML) showing the full request/response flow between services.

Tip: You can visually separate the setup (arrange) phase from the action phase using the SeparateSetup flag.

How It Works ↑

┌─────────────┐     HTTP      ┌─────────────┐     HTTP      ┌─────────────┐
│  Test Code  │ ──────────►   │     SUT     │ ──────────►   │ Dependency  │
│  (Caller)   │ ◄──────────   │  (Your API) │ ◄──────────   │  (Fakes)    │
└─────────────┘               └──────┬──────┘               └─────────────┘
                                     │
                        ┌────────────┼────────────┐
                        │            │            │
                        ▼            ▼            ▼
                  ┌──────────┐ ┌──────────┐ ┌──────────┐
                  │ CosmosDB │ │  SQL DB  │ │  Redis   │
                  │ (Fakes)  │ │ (Fakes)  │ │ (Fakes)  │
                  └──────────┘ └──────────┘ └──────────┘
                        │            │            │
           ┌────────────┼────────────┼────────────┘
           │            │            │
           │   Event / Message       │   Method calls
           │ ──────────────────►     │ ──────────────────►
           │  ┌──────────────┐       │  ┌──────────────┐
           │  │ Event broker │       │  │  Any service │
           │  │   (Fakes)    │       │  │ (via Proxy)  │
           │  └──────────────┘       │  └──────────────┘
           │                         │
           └─── All interactions are intercepted and logged ──┘
                                     │
                                     ▼
                          ┌──────────────────────┐
                          │ RequestResponseLogger│
                          │  (in-memory log)     │
                          └──────────┬───────────┘
                                     │
                                     ▼
                          ┌──────────────────────┐
                          │   PlantUmlCreator    │
                          │ (generates diagrams) │
                          └──────────┬───────────┘
                                     │
                                     ▼
                          ┌──────────────────────┐
                          │   ReportGenerator    │
                          │  (HTML + YAML files) │
                          └──────────────────────┘

Intercept — Each type of dependency has a dedicated tracking mechanism that logs interactions to the same in-memory store:

Dependency	Tracking mechanism	How it works
HTTP	`TestTrackingMessageHandler`	`DelegatingHandler` in the HTTP pipeline — logs method, URI, headers, body, status code
Azure Cosmos DB	`CosmosTrackingMessageHandler`	`DelegatingHandler` injected via `CosmosClientOptions.HttpClientFactory` — classifies operations (Query, Create, Upsert, etc.) with configurable verbosity
SQL (EF Core)	`SqlTrackingInterceptor`	`DbCommandInterceptor` — intercepts SQL commands from any relational provider (SQL Server, PostgreSQL, MySQL, SQLite, etc.)
Redis	`RedisTrackingDatabase`	`DispatchProxy` wrapping `IDatabase` — tracks GET, SET, HSET, LPUSH, PUBLISH, etc. with cache hit/miss status
Any interface	`TrackingProxy<T>`	.NET `DispatchProxy` wrapping any interface — logs method calls, arguments, return values, and exceptions
Events / messages	`MessageTracker`	Manual logging — for Kafka, RabbitMQ, EventGrid, or any message bus

See the Tracking Dependencies wiki page for setup guides.

Collect — All logged RequestResponseLog entries are held in the static RequestResponseLogger. Each entry captures the operation details, service names, and a trace ID to correlate requests across services.
Generate — At the end of the test run, PlantUmlCreator groups logs by test ID and converts them into sequence diagram code. PlantUML diagrams are encoded and rendered via a PlantUML server (or locally via IKVM), or rendered client-side in the browser.
Report — ReportGenerator combines the diagrams with test metadata (features, scenarios, results, BDD steps) to produce three output files: a YAML specification, an HTML specification with diagrams, and an HTML test run report.

Use Cases ↑

Debugging failed tests locally and in CI/staging

When a test fails, the sequence diagram shows exactly which interaction returned an unexpected result — whether it's an HTTP call, a database query, a Redis command, or a method call. Status codes, headers, payloads, and SQL text are all visible in the diagram notes. This eliminates guesswork when diagnosing failures, whether you're debugging locally or triaging a failed CI pipeline run against a staging environment. Instead of adding logging, re-running, and reading through console output, the diagram gives you the full picture in a single image.

Living documentation for stakeholders, developers, and AI

The generated HTML reports and YAML specifications serve as an always-up-to-date source of truth for how your API behaves. Because they're produced directly from passing tests, they can never drift out of sync with the actual implementation. Stakeholders can browse the HTML reports to understand feature behaviour without reading code. Developers can use them during onboarding or when working in unfamiliar areas of the codebase. AI assistants can consume the YAML specs or PlantUML source to answer questions about service interactions with high accuracy.

Feeding AI tools for more accurate analysis

The raw PlantUML code behind each diagram is a compact, structured representation of your service's interactions — HTTP calls, database queries, cache operations, events, and more. You can feed it directly into AI coding assistants, chat interfaces, or documentation generators to give them precise context about how services communicate. This produces significantly better results than asking an AI to infer behaviour from source code alone, because the diagrams capture the actual runtime flow including payloads, status codes, and service names.

Creating accurate high-level architecture diagrams

The per-test sequence diagrams provide a ground-truth foundation for building higher-level architecture and integration diagrams. Rather than drawing C4 models, system context diagrams, or integration maps from memory (which inevitably drift from reality), you or an AI can derive them from the concrete service interactions captured in the test suite. The PlantUML source is particularly useful here — an AI can aggregate the participants and message flows across multiple test diagrams to produce accurate summary diagrams.

Reviewing pull requests

When a PR changes service interactions (new downstream calls, modified payloads, changed queries, different cache patterns), the sequence diagrams in the test reports make the impact immediately visible. Reviewers can compare the before and after diagrams to understand exactly what changed, without having to mentally trace through the code.

Onboarding and knowledge transfer

New team members can browse the HTML reports to quickly understand how the system's services interact, what endpoints and data stores exist, and what the expected request/response shapes look like — all backed by real, passing tests rather than potentially stale wiki pages.

CI summary integration

Enable WriteCiSummary = true on your ReportConfigurationOptions to surface test results and sequence diagrams directly in your GitHub Actions job summary or Azure DevOps build summary. The summary includes a pass/fail table, and when tests fail, the failed scenarios are shown with error messages, stack traces, and their sequence diagrams — giving you immediate visual context without downloading artifacts. When all tests pass, diagrams for the first N scenarios are shown as a quick validation. See the CI Summary Integration wiki page for full details.

CI artifact upload

Enable PublishCiArtifacts = true to automatically publish generated report files as CI artifacts. On Azure DevOps, reports are uploaded directly via ##vso[artifact.upload] logging commands during test execution — no additional pipeline configuration needed. On GitHub Actions, the library writes the reports directory path and retention days to $GITHUB_OUTPUT so you can add a single upload-artifact step to your workflow. Artifact retention defaults to 1 day (CiArtifactRetentionDays). See the CI Artifact Upload wiki page for configuration and workflow examples.

Merging parallel reports

Splitting a large suite across several parallel CI runners is faster, but you still want one report. Set GenerateMergeableData = true so each runner emits an enriched TestRunReport.json, then run the kronikol .NET tool in a final job to combine them into a single TestRunReport.html — with the same information as a single combined run, including one merged Component Diagram across all runners:

dotnet tool install --global Kronikol.Tool
kronikol merge ./artifacts -o TestRunReport.html

See the Merging Parallel Reports wiki page for a full GitHub Actions example.

Deterministic vs AI-Generated Diagrams ↑

A key advantage of these diagrams is that they are deterministic — they are derived directly from actual interactions captured during test execution (HTTP traffic, database queries, cache commands, events, method calls), not generated by an AI model. AI-generated diagrams are non-deterministic by nature: they vary between runs, may hallucinate service interactions that don't exist, omit ones that do, or represent payloads inaccurately. The accuracy depends entirely on the model's understanding of your codebase, which is always incomplete.

Because Kronikol captures what actually happened at runtime, the output is a faithful, reproducible record of your system's behaviour. This makes the diagrams and PlantUML source especially valuable as input to AI tools — when you give an AI a deterministic, verified diagram as context, it can produce far more accurate outputs for:

Debugging — The AI sees the exact chain of interactions that led to a failure, rather than guessing from code paths
Code understanding — The AI can reason about concrete service interactions instead of inferring them from scattered registrations and handler code
Diagram generation — The AI can aggregate verified low-level sequence diagrams into accurate high-level architecture diagrams, C4 models, or integration maps
Documentation — The AI can write accurate API behaviour descriptions grounded in real data rather than its own interpretation of the source code

In short: use deterministic diagrams as the source of truth, and let AI tools build on top of that truth rather than trying to reconstruct it.

Supported Frameworks & NuGet Packages ↑

Framework	Package	Test Runner
Core library	`Kronikol`	—
xUnit v3	`Kronikol.xUnit3`	xUnit v3
xUnit v2	`Kronikol.xUnit2`	xUnit v2
NUnit	`Kronikol.NUnit4`	NUnit v4
MSTest	`Kronikol.MSTest`	MSTest v3
TUnit	`Kronikol.TUnit`	TUnit
BDDfy	`Kronikol.BDDfy.xUnit3`	xUnit v3
LightBDD	`Kronikol.LightBDD.xUnit2`	xUnit v2
LightBDD	`Kronikol.LightBDD.xUnit3`	xUnit v3
LightBDD	`Kronikol.LightBDD.TUnit`	TUnit
ReqNRoll	`Kronikol.ReqNRoll.xUnit2`	xUnit v2
ReqNRoll	`Kronikol.ReqNRoll.xUnit3`	xUnit v3
ReqNRoll	`Kronikol.ReqNRoll.TUnit`	TUnit

Extensions — Databases & Caches

Extension	Package	Description
Atlas Data API	`Kronikol.Extensions.AtlasDataApi`	Tracks MongoDB Atlas Data API HTTP operations (Find, Insert, Update, Delete, Aggregate) with configurable verbosity
BigQuery	`Kronikol.Extensions.BigQuery`	Tracks Google BigQuery operations with configurable verbosity
Bigtable	`Kronikol.Extensions.Bigtable`	Tracks Google Cloud Bigtable operations (ReadRows, MutateRow, CheckAndMutateRow, etc.) with configurable verbosity
ClickHouse	`Kronikol.Extensions.ClickHouse`	Tracks ClickHouse operations via `DbConnection` wrapping — works with both `ClickHouse.Client` and `Octonica.ClickHouseClient`. Classifies ClickHouse SQL including `ALTER TABLE … UPDATE/DELETE` mutations, `OPTIMIZE`, `RENAME`, `ATTACH/DETACH`
CosmosDB	`Kronikol.Extensions.CosmosDB`	Tracks Azure Cosmos DB SDK operations with classified labels (Create, Read, Query, etc.) and configurable verbosity
Dapper	`Kronikol.Extensions.Dapper`	Wraps `DbConnection` to intercept and classify Dapper/ADO.NET SQL queries with configurable verbosity. Works with any ADO.NET provider
DynamoDB	`Kronikol.Extensions.DynamoDB`	Tracks Amazon DynamoDB operations (PutItem, GetItem, Query, Scan, Batch, Transactions, PartiQL) with configurable verbosity
EF Core Relational	`Kronikol.Extensions.EfCore.Relational`	Tracks SQL operations from any EF Core relational provider (SQL Server, PostgreSQL, MySQL, SQLite, Oracle, Spanner) with classified labels and configurable verbosity
Elasticsearch	`Kronikol.Extensions.Elasticsearch`	Tracks Elasticsearch index, search, document, and cluster operations via the Elastic .NET client with configurable verbosity
MongoDB	`Kronikol.Extensions.MongoDB`	Tracks MongoDB operations (Find, Insert, Update, Delete, Aggregate, BulkWrite) via the driver's command event system with configurable verbosity
MySqlConnector	`Kronikol.Extensions.MySqlConnector`	Tracks MySQL operations via DiagnosticSource with zero production code changes and configurable verbosity
Npgsql	`Kronikol.Extensions.Npgsql`	Tracks PostgreSQL operations via DiagnosticSource with zero production code changes and configurable verbosity
Oracle	`Kronikol.Extensions.Oracle`	Tracks Oracle SQL operations via `DbConnection` wrapping with configurable verbosity
Redis	`Kronikol.Extensions.Redis`	Tracks StackExchange.Redis operations with cache hit/miss visualization, classified labels (Get, Set, Delete, Hash, List, etc.) and configurable verbosity
Spanner	`Kronikol.Extensions.Spanner`	Tracks Google Cloud Spanner operations via both ADO.NET and low-level gRPC interception with configurable verbosity
SqlClient	`Kronikol.Extensions.SqlClient`	Tracks SQL Server operations via DiagnosticSource with zero production code changes and configurable verbosity
SQLite	`Kronikol.Extensions.Sqlite`	Tracks SQLite operations via `DbConnection` wrapping with configurable verbosity

Extensions — Messaging & Events

Extension	Package	Description
EventBridge	`Kronikol.Extensions.EventBridge`	Tracks Amazon EventBridge operations (PutEvents, Rule management, EventBus) via the AWS SDK HTTP pipeline with configurable verbosity
Event Hubs	`Kronikol.Extensions.EventHubs`	Tracks Azure Event Hubs operations (Send, SendBatch, Receive, Process) with configurable verbosity
Kafka	`Kronikol.Extensions.Kafka`	Wraps `IProducer` and `IConsumer` to track Produce/Consume operations with configurable verbosity
Kafka Build Interception	`Kronikol.Extensions.Kafka.BuildInterception`	Automatic `ConsumerBuilder`/`ProducerBuilder.Build()` interception via Harmony for zero-prod-change Kafka tracking
MassTransit	`Kronikol.Extensions.MassTransit`	Tracks MassTransit Send, Publish, and Consume operations across RabbitMQ, Azure Service Bus, Amazon SQS, and other transports
Pub/Sub	`Kronikol.Extensions.PubSub`	Tracks Google Cloud Pub/Sub publish/receive operations with topic/subscription names and configurable verbosity
Service Bus	`Kronikol.Extensions.ServiceBus`	Tracks Azure Service Bus operations (Send, Receive, Complete, Abandon, DeadLetter, Defer, Schedule) with configurable verbosity
SNS	`Kronikol.Extensions.SNS`	Tracks Amazon SNS operations (Publish, Subscribe, CreateTopic) with configurable verbosity
SQS	`Kronikol.Extensions.SQS`	Tracks Amazon SQS operations (SendMessage, ReceiveMessage, DeleteMessage, ChangeVisibility) with configurable verbosity
Storage Queues	`Kronikol.Extensions.StorageQueues`	Tracks Azure Storage Queue operations (Send, Receive, Peek, Delete, Update, Clear) with configurable verbosity

Extensions — Cloud Storage

Extension	Package	Description
Blob Storage	`Kronikol.Extensions.BlobStorage`	Tracks Azure Blob Storage operations with configurable verbosity
Cloud Storage	`Kronikol.Extensions.CloudStorage`	Tracks Google Cloud Storage operations (Upload, Download, Delete, List, Copy, Compose) with configurable verbosity
S3	`Kronikol.Extensions.S3`	Tracks Amazon S3 operations (Upload, Download, Delete, List, Copy, Multipart) with configurable verbosity

Extensions — Application Frameworks & Tooling

Extension	Package	Description
Assertion Tracking	`Kronikol.AssertionTracking`	IL weaver that instruments FluentAssertions/AwesomeAssertions/TUnit assertions `.Should()` calls with assertion tracking, preserving full C# semantics
DispatchProxy	`Kronikol.Extensions.DispatchProxy`	DI integration helpers for `TrackingProxy<T>` — provides `ReplaceWithTracked<T>()` for `IServiceCollection`
gRPC	`Kronikol.Extensions.Grpc`	Tracks gRPC unary, server-streaming, client-streaming, and duplex-streaming calls with service/method names
MediatR	`Kronikol.Extensions.MediatR`	Wraps `IMediator` and `ISender` with `TrackingProxy` to record Send, Publish, and CreateStream calls with command/query type names
OpenTelemetry	`Kronikol.Extensions.OpenTelemetry`	Captures internal SUT spans during tests for internal flow visualization in sequence diagram popups
PlantUML IKVM	`Kronikol.PlantUml.Ikvm`	Local PlantUML rendering via IKVM — no remote server or Java installation required
Step Tracking	`Kronikol.StepTracking`	IL weaver that instruments `[GivenStep]`, `[WhenStep]`, `[ThenStep]` methods with BDD step tracking and timing

All packages from 1.23.X onwards target .NET 8.0, .NET 9.0, and .NET 10.0 (multi-target).

Documentation ↑

For full documentation including quick start guides, configuration, customisation, and API reference, see the Wiki.

Key pages:

Name		Name	Last commit message	Last commit date
Latest commit History 872 Commits
.claude		.claude
.github		.github
examples		examples
prototypes		prototypes
src		src
templates		templates
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Directory.Build.props		Directory.Build.props
Kronikol.sln		Kronikol.sln
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
global.json		global.json
icon.png		icon.png
icon.svg		icon.svg
nuget-readme.md		nuget-readme.md
release.slnf		release.slnf

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation