feat: Add custom admonitions for performance and migration tips

Author: thomhurst

docs/docs/advanced/performance-best-practices.md

@@ -2,6 +2,10 @@
 
 This guide provides recommendations for optimizing test performance and ensuring your TUnit test suite runs efficiently.
 
+:::performance
+Want to see how fast TUnit can be? Check out the [performance benchmarks](/docs/benchmarks) showing real-world speed comparisons, or use the [benchmark calculator](/docs/benchmarks/calculator) to estimate potential time savings for your specific test suite.
+:::
+
 ## Test Discovery Performance
 
 ### Use AOT Mode
@@ -15,6 +19,10 @@ TUnit's AOT (Ahead-of-Time) compilation mode provides the best performance for t
 </PropertyGroup>
 ```
 
+:::performance Native AOT Performance
+TUnit with Native AOT compilation delivers exceptional speed improvements - benchmarks show **11.65x faster** execution compared to regular JIT. See the [AOT benchmarks](/docs/benchmarks) for detailed measurements.
+:::
+
 Benefits:
 - Faster test discovery
 - Lower memory usage

docs/docs/assertions/getting-started.md

@@ -250,6 +250,134 @@ await Assert.That(number).IsEqualTo(42);
 // await Assert.That(number).IsEqualTo("42");
 ```
 
+## Common Mistakes & Best Practices
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+### Forgetting to Await
+
+<Tabs>
+  <TabItem value="bad" label="❌ Bad - Missing Await" default>
+
+```csharp
+[Test]
+public void TestValue()
+{
+    // Compiler warning: assertion not awaited
+    Assert.That(result).IsEqualTo(42);
+}
+```
+
+**Problem:** Assertion never executes, test always passes even if it should fail.
+
+  </TabItem>
+  <TabItem value="good" label="✅ Good - Awaited Properly">
+
+```csharp
+[Test]
+public async Task TestValue()
+{
+    await Assert.That(result).IsEqualTo(42);
+}
+```
+
+**Why:** Awaiting ensures the assertion executes and can fail the test.
+
+  </TabItem>
+</Tabs>
+
+### Comparing Different Types
+
+<Tabs>
+  <TabItem value="bad" label="❌ Bad - Type Confusion">
+
+```csharp
+int number = 42;
+// This won't compile - can't compare int to string
+// await Assert.That(number).IsEqualTo("42");
+
+// Or this pattern that converts implicitly
+string value = GetValue();
+await Assert.That(value).IsEqualTo(42); // Won't compile
+```
+
+**Problem:** Type mismatches are caught at compile time, preventing runtime surprises.
+
+  </TabItem>
+  <TabItem value="good" label="✅ Good - Explicit Conversion">
+
+```csharp
+string value = GetValue();
+int parsed = int.Parse(value);
+await Assert.That(parsed).IsEqualTo(42);
+
+// Or test the string directly
+await Assert.That(value).IsEqualTo("42");
+```
+
+**Why:** Be explicit about what you're testing - the string value or its parsed equivalent.
+
+  </TabItem>
+</Tabs>
+
+### Collection Ordering
+
+<Tabs>
+  <TabItem value="bad" label="❌ Bad - Assuming Order">
+
+```csharp
+var items = GetItemsFromDatabase(); // Order not guaranteed
+await Assert.That(items).IsEqualTo(new[] { 1, 2, 3 });
+```
+
+**Problem:** Fails unexpectedly if database returns `[3, 1, 2]` even though items are equivalent.
+
+  </TabItem>
+  <TabItem value="good" label="✅ Good - Order-Independent">
+
+```csharp
+var items = GetItemsFromDatabase();
+await Assert.That(items).IsEquivalentTo(new[] { 1, 2, 3 });
+```
+
+**Why:** `IsEquivalentTo` checks for same items regardless of order, making tests more resilient.
+
+  </TabItem>
+</Tabs>
+
+### Multiple Related Assertions
+
+<Tabs>
+  <TabItem value="bad" label="❌ Bad - Sequential Assertions">
+
+```csharp
+await Assert.That(user.FirstName).IsEqualTo("John");
+await Assert.That(user.LastName).IsEqualTo("Doe");
+await Assert.That(user.Age).IsGreaterThan(18);
+// If first assertion fails, you won't see the other failures
+```
+
+**Problem:** Stops at first failure, hiding other issues.
+
+  </TabItem>
+  <TabItem value="good" label="✅ Good - Assert.Multiple">
+
+```csharp
+await using (Assert.Multiple())
+{
+    await Assert.That(user.FirstName).IsEqualTo("John");
+    await Assert.That(user.LastName).IsEqualTo("Doe");
+    await Assert.That(user.Age).IsGreaterThan(18);
+}
+// Shows ALL failures at once
+```
+
+**Why:** See all failures in one test run, saving debugging time.
+
+  </TabItem>
+</Tabs>
+
 ## Next Steps
 
 Now that you understand the basics, explore specific assertion types:

docs/docs/assertions/library.md

@@ -0,0 +1,9 @@
+---
+title: Assertions Library
+description: Searchable library of all TUnit assertions
+sidebar_position: 100
+---
+
+import AssertionsLibrary from '@site/src/components/AssertionsLibrary';
+
+<AssertionsLibrary />

docs/docs/intro.md

@@ -8,3 +8,7 @@ It provides you a skeleton framework to write, execute and assert tests, with li
 That means you get more control over your setup, execution, and style of tests.
 
 It is also built on top of the newer Microsoft Testing Platform, which was rewritten to make .NET testing simpler and more extensible.
+
+:::performance
+TUnit is designed for speed. Through source generation and compile-time optimizations, TUnit significantly outperforms traditional testing frameworks. See the [performance benchmarks](/docs/benchmarks) or try the [benchmark calculator](/docs/benchmarks/calculator) to estimate time savings for your test suite.
+:::

docs/docs/migration/mstest.md

@@ -1,5 +1,9 @@
 # Migrating from MSTest
 
+:::from-mstest Performance Boost
+Migrating from MSTest to TUnit can significantly improve test execution speed. Benchmarks show TUnit is **1.3x faster** than MSTest on average. Check the [detailed benchmarks](/docs/benchmarks) to see performance comparisons.
+:::
+
 ## Quick Reference
 
 | MSTest | TUnit |

docs/docs/migration/nunit.md

@@ -1,5 +1,9 @@
 # Migrating from NUnit
 
+:::from-nunit Performance Boost
+Migrating from NUnit to TUnit can significantly improve test execution speed. Benchmarks show TUnit is **1.2x faster** than NUnit on average. Check the [detailed benchmarks](/docs/benchmarks) to see performance comparisons.
+:::
+
 ## Quick Reference
 
 | NUnit | TUnit |

docs/docs/migration/xunit.md

@@ -1,5 +1,9 @@
 # Migrating from xUnit.net
 
+:::from-xunit Performance Boost
+Migrating from xUnit to TUnit can significantly improve test execution speed. Benchmarks show TUnit is **1.3x faster** than xUnit v3 on average. Check the [detailed benchmarks](/docs/benchmarks) to see performance comparisons.
+:::
+
 ## Quick Reference
 
 | xUnit | TUnit |

docs/docs/parallelism/not-in-parallel.md

@@ -1,6 +1,10 @@
 # Not in Parallel
 
-By default, TUnit tests will run in parallel. 
+By default, TUnit tests will run in parallel.
+
+:::performance
+Parallel execution is a major contributor to TUnit's speed advantage. Running tests in parallel can dramatically reduce total test suite execution time. See the [performance benchmarks](/docs/benchmarks) for real-world performance data.
+::: 
 
 To remove this behaviour, we can add a `[NotInParallel]` attribute to our test methods or classes.
 

docs/docs/test-authoring/things-to-know.md

@@ -31,7 +31,11 @@ Then `MyTest1` and `MyTest2` will have a different instance of `MyTests`.
 
 This isn't that important unless you're storing state.
 
-So you can't do this:
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="bad" label="❌ Bad - Will Fail" default>
 
 ```csharp
 public class MyTests
@@ -42,15 +46,19 @@ public class MyTests
     public void MyTest1() { _value = 99; }
 
     [Test, NotInParallel]
-    public async Task MyTest2() { await Assert.That(_value).IsEqualTo(99); }
+    public async Task MyTest2()
+    {
+        // This will FAIL because _value is 0
+        // Different test instance = different _value
+        await Assert.That(_value).IsEqualTo(99);
+    }
 }
 ```
 
-The above will compile fine and run, but it will result in a failing test.
-
-Because `MyTests` in `MyTest2` is different from `MyTests` in `MyTest1`, therefore the `_value` field is a different reference.
+**Why this fails:** Each test gets a new instance of `MyTests`, so `_value` in `MyTest2` is a different field than in `MyTest1`.
 
-If you really want to perform a test like the above, you can make your field static, and then that field will persist across any instance. The `static` keyword makes it clear to the user that data persists outside of instances.
+  </TabItem>
+  <TabItem value="good" label="✅ Good - Use Static">
 
 ```csharp
 public class MyTests
@@ -61,6 +69,15 @@ public class MyTests
     public void MyTest1() { _value = 99; }
 
     [Test, NotInParallel]
-    public async Task MyTest2() { await Assert.That(_value).IsEqualTo(99); }
+    public async Task MyTest2()
+    {
+        // This works because _value is static
+        await Assert.That(_value).IsEqualTo(99);
+    }
 }
 ```
+
+**Why this works:** The `static` keyword makes the field persist across instances, making it clear that data is shared.
+
+  </TabItem>
+</Tabs>