V2

.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'docs/**'
+      - 'source/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Needed for git tags
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Update version info
+        working-directory: docs
+        run: npm run update-version
+
+      - name: Extract API docs from D source
+        working-directory: docs
+        run: npm run extract-docs
+
+      - name: Build documentation site
+        working-directory: docs
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,6 +1,12 @@
 .dub
 docs.json
 __dummy.html
+
+# Documentation site (Starlight/Astro)
+docs/node_modules/
+docs/dist/
+docs/.astro/
+docs/public/version.json
 *.o
 *.obj
 *.lst

README.md

@@ -66,6 +66,22 @@ expect(testedValue).to.not.equal(42);
     /// will output this message: Because of test reasons, true should equal `false`.
 ```
 
+`because` also supports format strings for dynamic messages:
+
+```D
+    foreach (i; 0..100) {
+        result.should.equal(expected).because("at iteration %s", i);
+    }
+```
+
+`withContext` attaches key-value debugging data:
+
+```D
+    result.should.equal(expected)
+        .withContext("userId", 42)
+        .withContext("input", testInput);
+    /// On failure, displays: CONTEXT: userId = 42, input = ...
+```
 
 ## Should
 
@@ -109,53 +125,190 @@ just add `not` before the assert name:
     Assert.notEqual(testedValue, 42);
 ```
 
+## Recording Evaluations
+
+The `recordEvaluation` function allows you to capture the result of an assertion without throwing an exception on failure. This is useful for testing assertion behavior itself, or for inspecting the evaluation result programmatically.
+
+```D
+import fluentasserts.core.lifecycle : recordEvaluation;
+
+unittest {
+    auto evaluation = ({
+        expect(5).to.equal(10);
+    }).recordEvaluation;
+
+    // Inspect the evaluation result
+    assert(evaluation.result.expected == "10");
+    assert(evaluation.result.actual == "5");
+}
+```
+
+The function:
+1. Takes a delegate containing the assertion to execute
+2. Temporarily disables failure handling so the test doesn't abort
+3. Returns the `Evaluation` struct containing the result
+
+The `Evaluation.result` provides access to:
+- `expected` - the expected value as a string
+- `actual` - the actual value as a string
+- `negated` - whether the assertion was negated with `.not`
+- `missing` - array of missing elements (for collection comparisons)
+- `extra` - array of extra elements (for collection comparisons)
+
+This is particularly useful when writing tests for custom assertion operations or when you need to verify that assertions produce the correct error messages.
+
+## Assertion Statistics
+
+fluent-asserts tracks assertion counts for monitoring test behavior:
+
+```D
+import fluentasserts.core.lifecycle : Lifecycle;
+
+// Run some assertions
+expect(1).to.equal(1);
+expect("hello").to.contain("ell");
+
+// Access statistics
+auto stats = Lifecycle.instance.statistics;
+writeln("Total: ", stats.totalAssertions);
+writeln("Passed: ", stats.passedAssertions);
+writeln("Failed: ", stats.failedAssertions);
+
+// Reset statistics
+Lifecycle.instance.resetStatistics();
+```
+
+The `AssertionStatistics` struct contains:
+- `totalAssertions` - Total number of assertions executed
+- `passedAssertions` - Number of assertions that passed
+- `failedAssertions` - Number of assertions that failed
+- `reset()` - Resets all counters to zero
+
+## Release Build Configuration
+
+By default, fluent-asserts behaves like D's built-in `assert`: assertions are enabled in debug builds and disabled (become no-ops) in release builds. This allows you to use fluent-asserts as a replacement for `assert` in your production code without any runtime overhead in release builds.
+
+**Default behavior:**
+- Debug build: assertions enabled
+- Release build (`dub build -b release` or `-release` flag): assertions disabled (no-op)
+
+**Force enable in release builds:**
+
+dub.sdl:
+```sdl
+versions "FluentAssertsDebug"
+```
+
+dub.json:
+```json
+{
+    "versions": ["FluentAssertsDebug"]
+}
+```
+
+**Force disable in all builds:**
+
+dub.sdl:
+```sdl
+versions "D_Disable_FluentAsserts"
+```
+
+dub.json:
+```json
+{
+    "versions": ["D_Disable_FluentAsserts"]
+}
+```
+
+**Check at compile-time:**
+```D
+import fluent.asserts;
+
+static if (fluentAssertsEnabled) {
+    // assertions are active
+} else {
+    // assertions are disabled (release build)
+}
+```
+
+## Custom Assert Handler
+
+During unittest builds, the library automatically installs a custom handler for D's built-in `assert` statements. This provides fluent-asserts style error messages even when using standard `assert`:
+
+```D
+unittest {
+    assert(1 == 2, "math is broken");
+    // Output includes ACTUAL/EXPECTED formatting and source location
+}
+```
+
+The handler is only active during `version(unittest)` builds, so it won't affect release builds. It is installed using `pragma(crt_constructor)`, which runs before druntime initialization. This approach avoids cyclic module dependency issues that would occur with `static this()`.
+
+If you need to temporarily disable this handler during tests:
+
+```D
+import core.exception;
+
+// Save and restore the handler
+auto savedHandler = core.exception.assertHandler;
+scope(exit) core.exception.assertHandler = savedHandler;
+
+// Disable fluent handler
+core.exception.assertHandler = null;
+```
+
 ## Built in operations
 
-- [above](api/above.md)
-- [approximately](api/approximately.md)
-- [beNull](api/beNull.md)
-- [below](api/below.md)
-- [between](api/between.md)
-- [contain](api/contain.md)
-- [containOnly](api/containOnly.md)
-- [endWith](api/endWith.md)
-- [equal](api/equal.md)
-- [greaterOrEqualTo](api/greaterOrEqualTo.md)
-- [greaterThan](api/greaterThan.md)
-- [instanceOf](api/instanceOf.md)
-- [lessOrEqualTo](api/lessOrEqualTo.md)
-- [lessThan](api/lessThan.md)
-- [startWith](api/startWith.md)
-- [throwAnyException](api/throwAnyException.md)
-- [throwException](api/throwException.md)
-- [throwSomething](api/throwSomething.md)
-- [withMessage](api/withMessage.md)
-- [within](api/within.md)
+
+
+### Memory Assertions
+
+The library provides assertions for checking memory allocations:
+
+```D
+// Check GC allocations
+({ auto arr = new int[100]; }).should.allocateGCMemory();
+({ int x = 5; }).should.not.allocateGCMemory();
+
+// Check non-GC allocations (malloc, etc.)
+({
+    import core.stdc.stdlib : malloc, free;
+    auto p = malloc(1024);
+    free(p);
+}).should.allocateNonGCMemory();
+```
+
+**Note:** Non-GC memory measurement uses process-wide metrics (`mallinfo` on Linux, `phys_footprint` on macOS). This is inherently unreliable during parallel test execution because allocations from other threads are included. For accurate non-GC memory testing, run tests single-threaded with `dub test -- -j1`.
 
 # Extend the library
 
 ## Registering new operations
 
-Even though this library has an extensive set of operations, sometimes a new operation might be needed to test your code. Operations are functions that recieve an `Evaluation` and returns an `IResult` list in case there was a failure. You can check any of the built in operations for a refference implementation.
+Even though this library has an extensive set of operations, sometimes a new operation might be needed to test your code. Operations are functions that receive an `Evaluation` and modify it to indicate success or failure. The operation sets the `expected` and `actual` fields on `evaluation.result` when there is a failure. You can check any of the built in operations for a reference implementation.
 
 ```d
-IResult[] customOperation(ref Evaluation evaluation) @safe nothrow {
-    ...
+void customOperation(ref Evaluation evaluation) @safe nothrow {
+    // Perform your check
+    bool success = /* your logic */;
+
+    if (!success) {
+        evaluation.result.expected = "expected value description";
+        evaluation.result.actual = "actual value description";
+    }
 }
 ```
 
 Once the operation is ready to use, it has to be registered with the global registry:
 
 ```d
 static this() {
-    /// bind the type to different matchers
+    // bind the type to different matchers
     Registry.instance.register!(SysTime, SysTime)("between", &customOperation);
     Registry.instance.register!(SysTime, SysTime)("within", &customOperation);
 
-    /// or use * to match any type
+    // or use * to match any type
     Registry.instance.register("*", "*", "customOperation", &customOperation);
 }
-
 ```
 
 ## Registering new serializers
@@ -164,14 +317,24 @@ In order to setup an `Evaluation`, the actual and expected values need to be con
 
 ```d
 static this() {
-    SerializerRegistry.instance.register(&jsonToString);
+    HeapSerializerRegistry.instance.register(&jsonToString);
 }
 
 string jsonToString(Json value) {
     /// you can add here your custom serializer for Jsons
 }
 ```
 
+# Contributing
+
+Areas for potential improvement:
+
+- **Reduce Evaluator duplication** - `Evaluator`, `TrustedEvaluator`, and `ThrowableEvaluator` share similar code that could be consolidated with templates or mixins.
+- **Simplify the Registry** - The type generalization logic could benefit from clearer naming or documentation.
+- **Remove ddmp dependency** - For simpler diffs or no diffs, removing the ddmp dependency would simplify the build.
+- **Consistent error messages** - Standardize error message patterns across operations for more predictable output.
+- **Make source extraction optional** - Source code tokenization runs on every assertion; making it opt-in could improve performance.
+- **GC allocation optimization** - Several hot paths use string/array concatenation that could be optimized with `Appender` or pre-allocation.
 
 # License