🎯 What is this? A tool that helps you see what your tests are doing, like a camera that records everything happening inside your tests!
Imagine you're playing with toys and want to know:
- 🎬 When did you start playing?
- ⏱️ How long did you play?
- 🧸 Which toys did you use?
- 📍 What happened step by step?
This tool does the same for your code tests!
🚀 Key Features:
- 📺 Built-in Test Output: All telemetry logs appear directly in your test output by default - no extra setup needed!
- 🔍 HTTP Request Tracing: See every web call your tests make with timing and response details
- ⚡ Zero Configuration: Works out of the box with minimal setup
- 🎯 Flexible Tracing: Trace all tests or just specific ones with attributes
Add it to your project:
dotnet add package xUnitOTelThe best part? All telemetry data appears directly in your test output by default! No need for external dashboards or complex setup - everything you need is right there in your test results.
As you can see above, HTTP requests, timing information, and trace IDs are automatically logged to your test output, making debugging and understanding your tests incredibly easy!
// Add this to any test file to trace ALL tests in your project
[assembly: Trace]
[assembly: AssemblyFixture(typeof(TestSetup))]See our complete working example in tests/xUnitOTel.Tests/TestSetup.cs
See our HTTP client testing example in tests/xUnitOTel.Tests/WebTests.cs
That's it! Your tests will now show telemetry data in the output.
**🎉 Benefits:**
- No need to add `[Trace]` to every test
- All tests in all classes get tracked automatically
- Great for existing projects - just add one line!
### Alternative: Trace Individual Tests
If you want to trace only specific tests, use the `[Trace]` attribute on individual test methods instead of the assembly-level attribute.
**📝 Note:** The `[Trace]` attribute won't work without the `TestSetup` configuration!
The xUnitOTel package, when configured with OTLP exporters as shown in the example below, outputs span data via gRPC to localhost:4317. To visualize this telemetry data, you can use the Aspire Dashboard which provides a user-friendly interface for viewing traces, metrics, and logs.
Run the Aspire Dashboard in a Docker container to view your test telemetry:
docker run -it -p 18888:18888 -p 4317:18889 -d -e DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS=true --name aspire-dashboard mcr.microsoft.com/dotnet/nightly/aspire-dashboard:8.0.0Then navigate to http://localhost:18888 to access the dashboard.
Think of the Host as a mini-application that runs during your tests. It's like having a toy kitchen when you want to play cooking - you need the kitchen (Host) to use the stove (HTTP client) and other tools!
The Host is also where the OpenTelemetry system lives - it's like the control room that watches and records everything.
It's like a security camera system for your code. It watches what happens and tells you about it!
No! For simple testing, use AddConsoleExporter() to see traces right in your test output. The Collector is for when you want to send traces to special monitoring tools like Jaeger or Zipkin.
The [Trace] attribute is like a light switch - but first you need to install the electrical system (AddOTelDiagnostics())! Without the setup, the switch has nothing to connect to.
- Use
[assembly: Trace]when you want to trace everything (recommended for most projects) - Use individual
[Trace]attributes when you only want to trace specific tests
- .NET 8.0 or later
- xUnit v3 (won't work with xUnit v2!)
- See test duration: Know which tests are slow
- Track HTTP calls: See all web requests your test makes
- Find failures: Quickly see what went wrong
- Understand flow: See the order of operations
Check out our examples folder for:
- Testing with databases
- Testing microservices
- Complex scenarios
- CI/CD integration
This project is licensed under the MIT License - see the LICENSE file for details.