The Complete Guide to kbmUnitTest

The kbmUnitTest framework ships with IDE wizards that live inside a single design-time BPL. Once installed, they let you scaffold complete test projects and test units without writing a single line of boilerplate — and a dedicated Mock Data Wizard helps you design mock-data scenarios visually. This post walks through installation, every option in each dialog, and the code that gets generated.

Installing the Wizard Package

The wizards are bundled in kbmTestWizardPackage.dpk. It is a design-time-only package that depends on rtl, vcl, and designide.

Steps:

1. Place all source files in a single directory (the framework .pas files, the wizard units, and the resource files kbmTestResources.rc / kbmTestResources.res).
2. Open kbmTestWizardPackage.dpk in the Delphi IDE.
3. Right-click the project in the Project Manager and choose Compile.
4. Right-click again and choose Install.

A message confirms “Package kbmTestWizardPackage.bpl has been installed“. The wizards are now registered in two places: under File → New → Other in a category called kbmUnitTest, and as three entries at the bottom of the Tools menu.

The package embeds the core framework source files (kbmTestFramework.pas, kbmTestRunner.pas, the FastMM adapter units, kbmTestDataSet.pas, and all kbmUnitTest.Mock.*.pas units) as RCDATA resources. When you create a new test project, the wizard extracts them automatically — no manual file copying required.

Accessing the Wizards

Via File → New → Other

Open File → New → Other… from the main menu:

In the New Items dialog, expand the Delphi node in the left-hand tree and select the kbmUnitTest category:

The category contains two entries:

Select the one you need and click OK to open the corresponding wizard dialog.

Via Tools Menu

All three wizards are also accessible directly from the Tools menu — no need to navigate through File → New → Other:

The three entries at the bottom are:

• kbmUnitTest New Test Project… — Opens the same Project Wizard dialog.
• kbmUnitTest New Test Unit… — Opens the same Unit Wizard dialog.
• kbmUnitTest Mock Wizard… — Opens the standalone Mock Data Wizard.

The Project Wizard

This is the dialog you see when you choose kbmUnitTest – Test Project:

The dialog is organized into clearly labeled sections. Every option is described below.

Project

Project Name — The name for the generated .dpr file. Defaults to TestProject1.

Location — Where the .dpr and test unit will be created. The dropdown is a most-recently-used (MRU) list: every directory you have used before is remembered across IDE sessions. Click Browse… to select a folder.

Test Unit

Create initial test unit — When checked (the default), the wizard creates a test-fixture unit alongside the project. Uncheck it if you only want the bare .dpr runner and plan to add units later via the Unit Wizard.

Unit Name — The file name for the generated test unit (without the .pas extension). Defaults to TestUnit1.

Fixture — The name of the generated test class, for example TTest2 or TOrderServiceTests. The wizard writes it into the [TestFixture] attribute and uses it for all method declarations.

Generated Code

Add Setup and TearDown methods — Generates [Setup] and [TearDown] stubs that run before and after each test method. Enable this when your tests need shared setup logic such as creating objects or opening database connections.

Add sample tests — Generates a few simple test methods so you have something that compiles and runs immediately. This is useful for verifying the framework is working before you write real tests.

Include comprehensive examples (all attributes & asserts) — A sub-option that becomes available when sample tests are enabled. When checked, the wizard generates a much larger unit that demonstrates every available attribute ([TestFixture], [Category], [SetupFixture], [TearDownFixture], [Setup], [TearDown], [Test], [ExpectedException], [Ignore], [MaxTime], [MemoryLeakAllowed], [Repeat], [TestCase], [Category]) and every Assert.* method (AreEqual, AreNotEqual, IsTrue, IsFalse, IsNull, IsNotNull, Contains, StartsWith, EndsWith, IsGreaterThan, IsLessThan, InRange, InheritsFrom, Implements, WillRaise, WillNotRaise, Pass, Fail, Inconclusive). It also includes ThatValue<T> fluent chains and, if DataSet support is enabled, ThatDataSet assertions. Think of it as a living cheat sheet you can compile and step through.

Optional Features

Include DataSet support (kbmTestDataSet) — Adds kbmTestDataSet to the uses clause and, in comprehensive mode, generates sample ThatDataSet fluent assertions against an in-memory dataset.

Include Mock system (kbmUnitTest.Mock) — Extracts the full mock-data unit set (kbmUnitTest.Mock.pas, kbmUnitTest.Mock.Rtti.pas, kbmUnitTest.Mock.JSON.pas, kbmUnitTest.Mock.CSV.pas, kbmUnitTest.Mock.Generators.pas, kbmUnitTest.Mock.DataSet.pas, kbmUnitTest.Mock.Graph.pas, kbmUnitTest.Mock.Diagnostics.pas, and supporting units) alongside the framework files.

• Generate sample mocks — Generates working test methods: TestMockScenario (looks up a named scenario and materializes it as a typed record) and TestMockGenerators (demonstrates Gen.Sequential, Gen.FloatRange, and Gen.OneOf). The initialization section registers the scenarios used by these tests.
• Include comprehensive reference — Extends the sample with additional tests covering inheritance, AsList<T>, AsObject<T>, AsObjectList<T>, raw field access, FromJSON, FromRecord, dot-notation paths, RTTI mapping attributes ([MockFieldName], [MockFieldIgnore], [MockFieldDefault]), registry querying, and — if DataSet is enabled — AsDataSet bridge materialization. It also defines sample TProduct and TAnnotatedProduct classes to demonstrate object-based materialization with attribute-driven field mapping.

Include TestInsight support (requires TestInsight plugin) — Adds kbmTestInsight to the uses clause and generates a {$IFDEF TESTINSIGHT} block in the .dpr that calls RunTestInsight for live IDE test feedback. This requires the TestInsight plugin to be installed separately (see Part 2 of this series for setup details).

Build Options

Memory Leak Detector — A dropdown with three choices:

Regardless of which you choose, the generated .dpr includes commented-out lines for the other two options so you can switch later by toggling a single comment.

Framework mode — Four radio buttons control how the generated project references the framework source files:

• Self-contained (extract sources) — The default. The wizard extracts all .pas files from its embedded resources into a subdirectory (shown in Framework Sources Directory) and generates in '...\kbmFramework\kbmTestFramework.pas' clauses in the .dpr. The subdirectory is also added to the project’s Unit Search Path. This mode is completely self-contained: copy the project folder to another machine and it compiles without any global configuration.
• External path (no extraction) — Points to a directory that already contains the framework files (perhaps a shared location on a network drive or a Git submodule). No files are extracted; the wizard only generates in clauses and adds the path to the search path. Use this when multiple projects share one copy of the framework.
• Delphi Library Path — Assumes the framework directory is already in your global Tools → Options → Library → Library Path. No files are extracted, no in clauses are generated, and no search-path entries are added. This is the cleanest option for teams that have added the framework to their shared library path.
• Specified path (add to search path) — Similar to external path, but only adds the directory to the project’s search path without generating in clauses in the uses list. Useful when you want minimal uses clutter but still need a per-project search path.

Framework Sources Directory — A combo box (with MRU history and a Browse… button) that specifies where framework sources are extracted to or referenced from. Enabled for Self-contained, External Path, and Specified Path modes. In Self-contained mode it defaults to a kbmFramework subdirectory under the project location. The wizard computes relative paths automatically when possible (up to four .. levels), falling back to absolute paths for distant directories or different drive letters.

Overwrite existing framework files — When checked, the wizard re-extracts every .pas file even if it already exists on disk. Useful after upgrading the wizard package to get the latest framework source. When unchecked, existing files are preserved so that any local modifications you have made are not lost.

Buttons

Defaults — Resets every option to its factory default. The MRU lists are preserved.

Cancel — Closes the dialog without creating anything.

Create Project — Creates the project, extracts framework files (if applicable), generates the test unit (if enabled), configures search paths, and persists all settings for next time.

Settings Persistence

All wizard options are stored in the registry under HKCU\Software\kbm\TestFramework. The next time you open the wizard — even after restarting the IDE — your previous choices are restored. This includes the fixture name, every checkbox state, the leak detector selection, the framework mode, and the framework directory.

The Unit Wizard

When you already have a test project open and want to add another fixture, choose kbmUnitTest – Test Unit from File → New → Other, or kbmUnitTest New Test Unit… from the Tools menu:

The Unit Wizard is a slimmed-down version of the Project Wizard. It does not show the Project section or Build Options because the unit is added to whichever project is currently active in the IDE. The sections you do see are:

Test Unit — Specify the unit file name and the fixture class name.

Generated Code — Same options as the Project Wizard: Setup/TearDown stubs, sample tests, and comprehensive reference.

Optional Features — Same options: DataSet support, Mock system (with sample mocks and comprehensive reference sub-options), and TestInsight support.

Overwrite existing framework files — Same behavior as in the Project Wizard.

When you click Create Unit the wizard:

1. Extracts framework files into the active project’s directory (unless they already exist and overwrite is unchecked).
2. If Mock system is enabled, extracts the mock units as well.
3. Creates the test unit in the project directory with your chosen fixture class and adds it to the project.

The generated unit opens immediately in the code editor, ready for you to rename or edit.

The Mock Data Wizard

The Mock Data Wizard is accessed from Tools → kbmUnitTest Mock Wizard…. It opens a standalone form that lets you design mock-data scenarios visually and generate the corresponding Delphi code or JSON fixture files.

From Type Tab

The From Type tab lets you paste a Delphi record or class type declaration, then click Parse Type Declaration to populate the field grid automatically:

For example, pasting:

TCustomerRec = record
    ID: Integer;
    Name: string;
    Active: Boolean;
    Balance: Currency;
end;

…and clicking Parse Type Declaration creates four rows in the field grid with the correct names and types pre-filled.

Manual Tab

The Manual tab lets you build field definitions by hand using the grid directly:

Use Add Field to insert rows and fill in each cell. This is useful for scenarios that do not correspond to an existing Delphi type.

Scenario List (Left Panel)

The left panel lists all scenarios in your current session. Use the +, −, and Dup buttons to add, remove, and duplicate scenarios. Clicking a scenario loads its fields into the grid.

Each scenario has:

• Name — The scenario name used in TkbmMockRegistry.Get('...') calls.
• Inherits — An optional parent scenario for inheritance. When set, the child scenario inherits all parent fields and only needs to override the ones that differ.
• Tabular (multi-row) — Check this to treat the scenario as a multi-row dataset (e.g., a product catalog with multiple rows). When unchecked, the scenario represents a single flat record.

Field Grid

The shared field grid is the heart of the wizard. Each row represents one field in the scenario:

Below the grid, the toolbar buttons let you manage fields:

• Add Field / Remove — Insert or delete field rows.
• ▲ / ▼ — Reorder fields.
• Add Row — When the scenario is tabular, adds another data row with its own set of values for all fields.

Output Options

At the bottom of the form:

Delphi Unit (.pas) — When checked, produces a complete Delphi unit with an initialization section that registers all scenarios using TkbmMockRegistry.Register(...). Field values become AddField('Name', value) calls, generator-backed fields become AddField('Name', Gen.Sequential(...)) calls, and inheritance is expressed via InheritsFrom('parent_name').

Unit name — The name for the generated .pas unit (e.g., TestData.Generated).

JSON Fixture (.json) — When checked, produces JSON fixture files that can be loaded at runtime via TkbmMockRegistry.LoadFromJSON(...).

Output dir — Where generated files are saved. Click … to browse. Defaults to the active project’s directory.

Preview — Shows the generated code in a preview window without writing to disk.

Generate — Writes the file(s) to disk.

Close — Closes the wizard.

Copy to Clipboard — Copies the generated Delphi code to the clipboard so you can paste it directly into an existing unit.

What Gets Generated

Generated Project (.dpr)

When you create a new test project with default settings, the wizard generates a .dpr that looks like this:

program TestProject1;
{$APPTYPE CONSOLE}
{$STRONGLINKTYPES ON}
{$R *.res}
uses
  // --- Memory Leak Detection ---
  // Active: Built-in detector (GetMemoryManagerState).
  // Uncomment one line below for enhanced leak detection
  // with class names and richer detail:
  // FastMM5, kbmTestFastMM5,         // FastMM5 enhanced leak detection
  // FastMM4, kbmTestFastMM4,         // FastMM4 FullDebugMode leak detection
  System.SysUtils,
  kbmTestFramework in '.\kbmFramework\kbmTestFramework.pas',
  kbmTestRunner in '.\kbmFramework\kbmTestRunner.pas';
var
  LXmlFile: string;
begin
  // Memory leak detection is ON by default in all modes.
  // Add --noleaks on the command line to disable.
  // Per-test opt-out: [MemoryLeakAllowed] or [MemoryLeakAllowed(1024)]
  //
  // CI mode:  MyTests.exe --ci [--xml results.xml] [--noleaks]
  //           Produces JUnit XML, leaks = failure.
  // Normal:   MyTests.exe [--noleaks]
  //           Console output, leaks = warning.
  if FindCmdLineSwitch('ci') then
  begin
    if FindCmdLineSwitch('xml', LXmlFile) then
      RunTestsForCI(LXmlFile, '', True,
        not FindCmdLineSwitch('noleaks'))
    else
      RunTestsForCI('test-results.xml', '', True,
        not FindCmdLineSwitch('noleaks'));
  end
  else
  begin
    RunTestsAndHalt('', True,
      not FindCmdLineSwitch('noleaks'));
    {$IFDEF DEBUG}
    WriteLn;
    Write('Press Enter to close...');
    ReadLn;
    {$ENDIF}
  end;
end.

Note the in clauses with relative paths — these are computed automatically from the project directory to the framework subdirectory. If you chose Delphi Library Path mode instead, those in clauses would be absent.

Generated Test Unit

With “Add Setup and TearDown methods” checked and “Add sample tests” unchecked, the generated unit contains a minimal ready-to-fill fixture:

unit TestUnit1;
interface
uses
  System.SysUtils,
  kbmTestFramework;
type
  [TestFixture]
  TTest2 = class
  public
    [Setup]
    procedure Setup;
    [TearDown]
    procedure TearDown;
    [Test]
    procedure TestSomething;
  end;
implementation
procedure TTest2.Setup;
begin
  // Runs before each test
end;
procedure TTest2.TearDown;
begin
  // Runs after each test
end;
procedure TTest2.TestSomething;
begin
  // TODO: Implement test
  Assert.Pass;
end;
end.

Workflow Recommendations

Starting a new test suite: Use the Project Wizard with self-contained mode. Check “Add sample tests” to get a green-bar confirmation that everything works. Once satisfied, delete the sample methods and start writing real tests.

Adding tests to an existing project: Use the Unit Wizard. It detects the active project’s directory and extracts any missing framework files automatically. You get a new fixture unit added to the project in one click.

Designing mock data visually: Use the Mock Wizard from the Tools menu. Paste your record type, click Parse Type Declaration, tweak values and generators in the grid, preview the output, and either generate a file or copy the code to clipboard. This is faster than writing TkbmMockRegistry.Register(...) calls by hand, especially for scenarios with many fields or multiple rows.

Sharing a test project with the team: Self-contained mode ensures that the framework source files travel with the project. Anyone who checks out the repository can compile immediately — they don’t need the wizard package installed, they don’t need the framework on their library path, and they don’t need to run any setup scripts.

Upgrading the framework: Install the new wizard BPL, open your existing test project, run the Project Wizard or Unit Wizard with “Overwrite existing framework files” checked, and point it at your existing project directory. The wizard re-extracts all .pas files with the latest versions while leaving your test units untouched.

Quick Reference

Summary

The wizard package eliminates the mechanical overhead of setting up a kbmUnitTest project. The Project Wizard scaffolds a complete console runner with framework sources, leak-detector configuration, TestInsight integration, and optional mock data — all in one dialog. The Unit Wizard adds fixture units to an existing project with a single click. The Mock Data Wizard lets you design scenarios visually, import fields from Delphi types, assign generators, and produce registration code or JSON fixtures without writing any boilerplate.

Install the BPL once, and every new test project starts with a green bar instead of a blank screen.