4 AL/BC testing patterns from an external BC testing expert's blog (Luc van Vugt, fluxxus.nl)

microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.bad.al

@@ -0,0 +1,34 @@
+codeunit 50142 "Sample Test Library"
+{
+    Subtype = Test;
+
+    var
+        Initialized: Boolean;
+        RollBackMsg: Label 'Revert back the tables to their original state.';
+
+    local procedure Initialize()
+    begin
+        if Initialized then
+            exit;
+
+        CreateSharedFixtureData();
+        Initialized := true;
+    end;
+
+    local procedure CreateSharedFixtureData()
+    begin
+        // insert master/setup data shared across every test in this codeunit
+    end;
+
+    [Test]
+    procedure FirstTestUsesSharedFixture()
+    begin
+        Initialize();
+
+        // exercise/verify against the shared fixture, then make scratch changes of its own
+
+        asserterror Error(RollBackMsg);
+        // the deliberate rollback above also erases the never-committed fixture;
+        // Initialized still reads true on the next test, but the rows are gone
+    end;
+}

microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.good.al

@@ -0,0 +1,33 @@
+codeunit 50142 "Sample Test Library"
+{
+    Subtype = Test;
+
+    var
+        Initialized: Boolean;
+        RollBackMsg: Label 'Revert back the tables to their original state.';
+
+    local procedure Initialize()
+    begin
+        if Initialized then
+            exit;
+
+        CreateSharedFixtureData();
+        Commit();
+        Initialized := true;
+    end;
+
+    local procedure CreateSharedFixtureData()
+    begin
+        // insert master/setup data shared across every test in this codeunit
+    end;
+
+    [Test]
+    procedure FirstTestUsesSharedFixture()
+    begin
+        Initialize();
+
+        // exercise/verify against the shared fixture, then make scratch changes of its own
+
+        asserterror Error(RollBackMsg);
+    end;
+}

microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.md

@@ -0,0 +1,34 @@
+---
+bc-version: [all]
+domain: testing
+keywords: [initialize, isinitialized, shared-fixture, commit, autocommit, asserterror, testisolation, lazy-initialization]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Commit shared fixture data created inside a lazy Initialize(), or later tests lose it
+
+## Description
+
+A test method with no `[TransactionModel(...)]` attribute defaults to `AutoCommit` (see `transactionmodel-attribute-governs-test-transactions.md`): a method that completes without error commits automatically at its own boundary, with no explicit `Commit()` needed. So a lazy/shared `Initialize()` — guarded by an `IsInitialized` flag, creating master/setup data once to avoid repeating expensive setup across many `[Test]` methods — does not need `Commit()` just to survive into the next test method; under the default model it already will. (Declaring `[TransactionModel(AutoRollback)]` instead is not compatible with this pattern at all: `AutoRollback` assumes the code under test never commits, and a `Commit()` call under it raises a runtime error.)
+
+What an early `Commit()` inside `Initialize()` actually guards against is the test method's *own later, deliberate* rollback — the BCApps cleanup idiom of ending a test with `asserterror Error(SomeLabel)` to undo demo-data mutations that method made, so the run doesn't permanently dirty the database. Per the documented `Codeunit.Run` transaction semantics, changes are committed at the end of an execution "unless an error occurs" — an unhandled error rolls back whatever wasn't already committed. `Commit()` closes out the fixture's own transaction immediately, so it is unaffected by whatever the rest of that method does afterward, including that end-of-test error. Without the early `Commit()`, the same deliberate rollback wipes out the fixture too, even though `IsInitialized` still reads `true` on the next test, since it's a plain variable, not persisted data. BCApps' `codeunit 134915 "ERM Online Mapping Setup"` shows exactly this shape: no `TransactionModel` attribute, `Commit()` inside a lazy `Initialize()`, and the test itself ends with `asserterror Error(RollBackMessage)`.
+
+Protecting the fixture from that same-method rollback is necessary but not sufficient for the fixture to reach a *later* test method — that also depends on the executing test runner's `TestIsolation`. Under `Disabled` (the property's own documented default) or `Codeunit` (used by BCApps' own `TestRunner`, `CLITestRunner`, and `SnapTestRunner` codeunits), nothing rolls back until the whole test codeunit finishes, so the already-committed fixture survives across every method run before then. Under `Function`, the runner rolls back all database changes — explicitly including ones already committed via `Commit()` — after every single test method; no amount of committing inside `Initialize()` makes a fixture shared across methods survive that regime, because the whole premise of a lazy, once-per-codeunit fixture doesn't hold when every method is isolated from every other.
+
+## Best Practice
+
+When a test method's own cleanup relies on ending in a deliberate error to roll back its scratch changes, call `Commit()` once, inside the lazy `Initialize()` guard, right after the shared fixture is created — before that cleanup-triggering error can run. This pattern only delivers a fixture shared across test methods when the executing runner's `TestIsolation` is `Disabled` or `Codeunit`; do not recommend it, or pair it with, a `Function`-isolated runner — that configuration undoes the committed fixture after every method regardless.
+
+See sample: `commit-shared-test-fixture-inside-lazy-initialize.good.al`.
+
+## Anti Pattern
+
+A shared `Initialize()` guarded by `IsInitialized` that creates fixture records without committing, in a test method that ends with a deliberate `asserterror Error(...)` to undo its own scratch changes, run under a `Disabled`- or `Codeunit`-isolated test runner. That rollback also erases the never-committed fixture; the next test still finds `IsInitialized = true` but the rows it depends on are gone. (Under a `Function`-isolated runner the fixture is lost regardless of `Commit()`, for the unrelated reason above — that is a runner-configuration problem, not this anti-pattern.)
+
+See sample: `commit-shared-test-fixture-inside-lazy-initialize.bad.al`.
+
+## Source
+
+The shared/lazy `Initialize()` pattern and its `Commit()` call are drawn from Luc van Vugt's "Let's talk about Shared Fixture and how to profit from this with the Dynamics NAV Test Toolkit": https://www.fluxxus.nl/index.php/bc/let39s-talk-about-shared-fixture-and-how-to-profit-from-this-with-the-dynamics-nav-test-toolkit/. That post shows the `Commit()` call in its `Initialize()` example but does not explain the transaction mechanics behind it; the `AutoCommit`-default, `Codeunit.Run`-error, and `TestIsolation`-level analysis above is this article's own, verified independently against Microsoft's TransactionModel/TestIsolation documentation and BCApps' `codeunit 134915 "ERM Online Mapping Setup"` source, not taken from the post.

microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.bad.al

@@ -0,0 +1,11 @@
+codeunit 50141 "Sample Table Relation Test Ext"
+{
+    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Table Relation Test", 'OnAfterRemoveTableRelation', '', false, false)]
+    local procedure ExcludeSampleFieldFromTableRelationTest(var TableRelationsMetadata: Record "Table Relations Metadata" temporary)
+    var
+        TableRelationTest: Codeunit "Table Relation Test";
+    begin
+        // Removes every relation on the whole table, not just the one known exception
+        TableRelationTest.RemoveTableRelation(TableRelationsMetadata, Database::"Sample Header", 0, 0, 0);
+    end;
+}

microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.good.al

@@ -0,0 +1,10 @@
+codeunit 50141 "Sample Table Relation Test Ext"
+{
+    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Table Relation Test", 'OnAfterRemoveTableRelation', '', false, false)]
+    local procedure ExcludeSampleFieldFromTableRelationTest(var TableRelationsMetadata: Record "Table Relations Metadata" temporary)
+    var
+        TableRelationTest: Codeunit "Table Relation Test";
+    begin
+        TableRelationTest.RemoveTableRelation(TableRelationsMetadata, Database::"Sample Header", 10, Database::"Sample Setup", 1);
+    end;
+}

microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.md

@@ -0,0 +1,30 @@
+---
+bc-version: [all]
+domain: testing
+keywords: [table-relation-test, tablerelationsmetadata, onafterremovetablerelation, field-length, field-type]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Exclude a known-valid TableRelation exception via OnAfterRemoveTableRelation
+
+## Description
+
+Codeunit 134926 "Table Relation Test" (shipped in BCApps' test app — only consumers that depend on the BC test libraries can subscribe to it) reads Table Relations Metadata tenant-wide across every installed app, not just the current one, and fails the moment a related field's type or length doesn't match what the relation requires — the related field must match the largest related field's length, and its type must match (except a field may relate to both `Code` and `Text`, which resolves to `Text`). A field with a legitimate, intentional relation shape has no per-field override in its own object definition; the check runs with no built-in escape hatch. The validation test method itself is `[Scope('OnPrem')]`: it only runs from an on-premises test surface, not from a cloud-targeted test app, so this whole exception mechanism — and the check it works around — is only reachable where that test can actually execute.
+
+## Best Practice
+
+Subscribe to `OnAfterRemoveTableRelation` and call the codeunit's own `RemoveTableRelation(TableRelationsMetadata, TableID, FieldID, RelatedTableID, RelatedFieldID)` to strike the one known-valid relation before the test evaluates it, scoped as narrowly as the exception actually is. Because the test itself is `[Scope('OnPrem')]`, do not recommend subscribing to it as a way to guard a cloud-targeted app's test suite — the subscription has no effect where the test never runs.
+
+See sample: `table-relation-test-exclude-known-invalid-relations-via-event.good.al`.
+
+## Anti Pattern
+
+Excluding an entire table's relations (or disabling the whole test codeunit) to work around one known exception. This discards the check's coverage for every other relation on that table, or in the app, not just the one that needed an exception.
+
+See sample: `table-relation-test-exclude-known-invalid-relations-via-event.bad.al`.
+
+## Source
+
+The `OnAfterRemoveTableRelation` exclusion technique is drawn from Luc van Vugt's "How-to: Test your Table Relations (2)": https://www.fluxxus.nl/index.php/bc/how-to-test-your-table-relations-2/. The codeunit/event signature, the `[Scope('OnPrem')]` boundary, and the tenant-wide `Table Relations Metadata` scope described above were verified directly against BCApps' `codeunit 134926 "Table Relation Test"` source, not taken from the post.

microsoft/knowledge/testing/transactionmodel-attribute-governs-test-transactions.md

@@ -11,16 +11,20 @@ application-area: [all]
 
 ## Description
 
-`[TransactionModel(...)]` declares how a test method interacts with the database's write transaction. The attribute applies only to methods inside a codeunit with `SubType = Test` and takes one of three values: `AutoRollback`, `AutoCommit`, or `None`. The choice must match the code being exercised — in particular, whether that code calls `Commit()`. Per the platform reference, "if the code that you test includes calls to the COMMIT Method, then set the TransactionModel property on the test method to AutoCommit." Applying `AutoRollback` to a test that drives code which calls `Commit` produces a runtime error on the first Commit, not a meaningful assertion failure — the test does not complete, and the reviewer sees an infrastructure error instead of a business-logic verdict.
+`[TransactionModel(...)]` declares how a test method interacts with the database's write transaction. The attribute applies only to methods inside a codeunit with `SubType = Test` and takes one of three values: `AutoRollback`, `AutoCommit`, or `None`. **`AutoCommit` is the documented default** — a test method with no `[TransactionModel(...)]` attribute at all runs under `AutoCommit`, not `AutoRollback` and not `None` (Microsoft's TransactionModel property reference states this explicitly: "AutoCommit is the default value"). The "a call to `Commit` produces a runtime error" behavior is specific to the *explicitly declared* `AutoRollback` attribute. BCApps' own canonical pattern for a lazily-initialized shared fixture (see `codeunit 134915 "ERM Online Mapping Setup"`) declares no `TransactionModel` attribute at all — so it runs under the `AutoCommit` default — calls `Commit()` inside its `Initialize()` helper, and cleans up manually with a deliberate `asserterror Error(...)` at the end rather than relying on automatic rollback; this is a legitimate, common pattern, not a bug. Per the same reference, under `AutoCommit` an error, even one caught by `asserterror`, still rolls back the transaction — but "only to the point at which `Commit` was called" if the code being tested committed first. When a test method *does* declare `AutoRollback` explicitly, the choice must match the code being exercised: per the platform reference, "if the code that you test includes calls to the COMMIT Method, then set the TransactionModel property on the test method to AutoCommit." Applying `AutoRollback` to a test that drives code which calls `Commit` produces a runtime error on the first Commit, not a meaningful assertion failure.
 
 ## Best Practice
 
-Default to `AutoRollback`: it opens a write transaction at the start of the test, runs the test body, and rolls back at the end, leaving the database in its original state. Pick `AutoCommit` only when the code under test genuinely calls `Commit` — posting routines, job-queue handlers, integration flows — and make the test exercise that commit path. Pair the test codeunit with a `TestIsolation`-enabled test runner so committed changes are reverted at a higher scope. Pick `None` only for read-only tests or tests that drive UI code without writing from the test method itself.
+Leave `[TransactionModel(...)]` undeclared to get the `AutoCommit` default when the codeunit's own tests rely on that default's behavior — for example a lazily-initialized shared fixture that commits once and cleans up its own scratch changes with a manual `asserterror`-based rollback (see `commit-shared-test-fixture-inside-lazy-initialize.md`); do not treat that absence as equivalent to declaring `AutoRollback`. When declaring `[TransactionModel(...)]` explicitly instead, pick `AutoRollback` for a test whose own logic and the code it exercises make no `Commit` call, `AutoCommit` when the code under test genuinely calls `Commit` — posting routines, job-queue handlers, integration flows — and make the test exercise that commit path, and `None` for a read-only test or one that drives UI code without writing from the test method itself. Pair an intentional, suite-wide reliance on `AutoCommit` with a `TestIsolation`-enabled test runner so committed changes are reverted at a higher scope.
 
 See sample: `transactionmodel-attribute-governs-test-transactions.good.al`.
 
 ## Anti Pattern
 
-Applying `AutoRollback` to every test method without checking whether the tested business logic calls `Commit`. The test throws at the first Commit, leaving no verdict on the behavior it intended to verify; in a CI run this looks like a flake or a setup bug, not a specification mismatch. The mirror-image anti-pattern is defaulting to `AutoCommit` across the suite "to avoid the error" — without a `TestIsolation` runner this permanently dirties the test database between runs and produces order-dependent test outcomes.
+Declaring `[TransactionModel(AutoRollback)]` explicitly on a test method without checking whether the tested business logic calls `Commit`. The test throws at the first Commit, leaving no verdict on the behavior it intended to verify; in a CI run this looks like a flake or a setup bug, not a specification mismatch. The mirror-image anti-pattern is defaulting to `AutoCommit` across the suite "to avoid the error" — without a `TestIsolation` runner this permanently dirties the test database between runs and produces order-dependent test outcomes. Flagging a `Commit()` call in a test method that declares no `TransactionModel` attribute at all is not this anti-pattern — that shape does not error, and is BCApps' own documented pattern for shared lazy fixtures.
 
 See sample: `transactionmodel-attribute-governs-test-transactions.bad.al`.
+
+## Source
+
+The `AutoCommit`-is-default claim and the exact rollback-to-last-`Commit` mechanics are quoted from Microsoft's TransactionModel Property reference: https://learn.microsoft.com/en-us/previous-versions/dynamicsnav-2018-developer/TransactionModel-Property. The current AL [TransactionModel attribute](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/attributes/devenv-transactionmodel-attribute) page describes the same three values but never states a default; this older property reference is the citable source for that fact.

microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.bad.al

@@ -0,0 +1,18 @@
+codeunit 50143 "Sample Doc Amount Test"
+{
+    Subtype = Test;
+
+    [Test]
+    procedure DocAmountIsNotVerifiedWhenLinesAreMissing()
+    var
+        Assert: Codeunit Assert;
+        PurchHeader: Record "Purchase Header";
+    begin
+        asserterror Assert.IsTrue(VerifyDocAmount(PurchHeader), 'Doc. amount should not verify with no lines.');
+    end;
+
+    local procedure VerifyDocAmount(var PurchHeader: Record "Purchase Header"): Boolean
+    begin
+        exit(false);
+    end;
+}

microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.good.al

@@ -0,0 +1,18 @@
+codeunit 50143 "Sample Doc Amount Test"
+{
+    Subtype = Test;
+
+    [Test]
+    procedure DocAmountIsNotVerifiedWhenLinesAreMissing()
+    var
+        Assert: Codeunit Assert;
+        PurchHeader: Record "Purchase Header";
+    begin
+        Assert.IsFalse(VerifyDocAmount(PurchHeader), 'Doc. amount should not verify with no lines.');
+    end;
+
+    local procedure VerifyDocAmount(var PurchHeader: Record "Purchase Header"): Boolean
+    begin
+        exit(false);
+    end;
+}