The Complete Guide to kbmUnitTest

This is part 2 of a 6-part series. Part 1 covered creating your first test project and using basic assertions.

What is TestInsight?

TestInsight, by Stefan Glienke, is a Delphi IDE plugin that runs your tests automatically in the background and shows results right in the editor gutter — green dots for passing tests, red dots for failures. When you save a file, tests re-run instantly. It is the closest thing Delphi has to the “live test” experience of tools like NCrunch for .NET or Wallaby.js for JavaScript.

kbmUnitTest integrates with TestInsight through a single optional unit, kbmTestInsight.pas. The integration posts results in real time — each test result appears in the IDE the moment it finishes, rather than waiting for the entire suite to complete.

Prerequisites

1. TestInsight installed — Download and install from bitbucket.org/sglienke/testinsight. After installation, you will see a TestInsight panel in the IDE (View → TestInsight Explorer).
2. TestInsight source path — The installer places source files (including TestInsight.Client.pas) in a directory like C:\Users\<you>\AppData\Local\Programs\TestInsight\Source. This path must be on your project’s search path so that kbmTestInsight.pas can find the TestInsight.Client unit it uses in its implementation section. Add it via Project → Options → Delphi Compiler → Search Path. The TestInsight client communicates with the IDE over HTTP using Indy (IdHTTP), which ships with Delphi — no extra installation is needed for that.
3. kbmTestInsight.pas — Copy this file alongside the other framework units in your library path.

Quick-start shortcut. Instead of adding the search path manually, you can right-click your project in the Project Manager and select TestInsight Project. This adds the TESTINSIGHT conditional define and the TestInsight source path in one step.

Setting Up Your Test Project

The key change is in your DPR file. You use a conditional define to switch between TestInsight mode (for the IDE) and normal console mode (for CI or command-line execution):

program MyTests;
{$APPTYPE CONSOLE}
{$STRONGLINKTYPES ON}
uses
  kbmTestFramework,
  kbmTestRunner,
  kbmTestInsight,       // <-- add this
  Test.Calculator in 'Test.Calculator.pas';
begin
  {$IFDEF TESTINSIGHT}
  RunTestInsight;
  {$ELSE}
  RunTests;
  {$ENDIF}
end.

Now add the conditional define:

1. Open Project → Options → Delphi Compiler → Conditional Defines.
2. Add TESTINSIGHT to the list.

When you run from the IDE, TESTINSIGHT is defined and RunTestInsight takes over. When you build for CI (where the define is not set), the project falls back to RunTests or RunTestsForCI.

How RunTestInsight Works

RunTestInsight performs the following steps:

1. Creates a TTestInsightRestClient (the concrete implementation of ITestInsightClient) which immediately attempts to connect to the TestInsight server running inside the IDE.
2. If the server is not found (HasError returns True — for example, you are running from the command line without the IDE), it falls back to RunTestsAndHalt automatically — no code changes needed.
3. Queries TestInsight for which tests to run. If the user has selected specific tests in the TestInsight Explorer, only those are executed. If none are selected, all tests run.
4. Creates a TkbmTestRunner, attaches a TkbmTestInsightLogger, and executes.
5. Each result is posted to the IDE in real time via ITestInsightClient.PostResult.

Memory leak detection is enabled by default in TestInsight mode (with lrmWarning — leaks are reported but do not fail the test). This gives you visibility into leaks during development without interrupting your flow.

The Developer Workflow

Once configured, the workflow is:

1. Open your test project in the IDE.
2. Open the TestInsight Explorer panel (View → TestInsight Explorer).
3. Press Run (or let the automatic run trigger on save).
4. Watch the gutter in your test source: green dots appear next to passing tests, red dots next to failures.
5. Click a red dot to see the failure message.
6. Fix the code, save, tests re-run automatically.

This tight feedback loop is transformative for test-driven development. You spend less time context-switching between the editor and a console window, and failures surface within seconds of introducing them.

Combining TestInsight with Other Loggers

If you need to, you can create the runner manually for finer control. This requires adding TestInsight.Client to your uses clause directly (the standard RunTestInsight path handles this internally):

procedure RunTestInsightCustom;
var
  LClient: ITestInsightClient;
  LRunner: TkbmTestRunner;
begin
  LClient := TTestInsightRestClient.Create;
  if LClient.HasError then
  begin
    RunTestsAndHalt;
    Exit;
  end;
  LRunner := TkbmTestRunner.Create;
  try
    // TestInsight logger for IDE integration
    LRunner.AddLogger(TkbmTestInsightLogger.Create(LClient));
    // Also log to console (useful when watching the output pane)
    LRunner.AddLogger(TkbmConsoleTestLogger.Create(False));
    LRunner.DetectMemoryLeaks := True;
    LRunner.LeakReportMode := lrmWarning;
    LRunner.Execute;
  finally
    LRunner.Free;
  end;
  // LClient is an interface reference — released automatically
end;

The runner supports any number of loggers attached simultaneously. Each logger receives every event — begin run, begin fixture, test result, end fixture, end run — so they all stay in sync.

Tips for TestInsight Usage

Define management. Some developers prefer to enable TESTINSIGHT only in the Debug build configuration. This way Release builds and CI builds never accidentally route through TestInsight:

• Debug configuration: TESTINSIGHT defined.
• Release / CI configuration: no TESTINSIGHT.

Selective test execution. In the TestInsight Explorer you can right-click a fixture or individual test and choose “Run Selected”. Only those tests execute, making the feedback loop even faster when you are focused on a specific area.

Leak reporting. When a test leaks memory, the leak information (byte count and, if FastMM5 is active, class names) is included in the TestInsight result message. Hover over the test in the explorer to see the details.

Summary

Adding TestInsight integration is a small change:

1. Ensure the TestInsight source path (e.g. C:\Users\<you>\AppData\Local\Programs\TestInsight\Source) is on your project’s search path — or right-click the project and choose TestInsight Project to set it up automatically.
2. Add kbmTestInsight to uses.
3. Call RunTestInsight inside an {$IFDEF TESTINSIGHT} block.
4. Add the TESTINSIGHT conditional define to your Debug configuration.

You get instant in-editor feedback, automatic re-runs on save, and a seamless fallback to console mode for CI. In Part 3 we will explore the framework’s advanced testing features: the fluent API, custom constraints, parameterized tests, categories, TDataSet assertions, and memory leak detection.The Complete Guide to kbmUnitTest — Part 2: Real-time Testing with TestInsight

This is part 2 of a 6-part series. Part 1 covered creating your first test project and using basic assertions.

What is TestInsight?

TestInsight, by Stefan Glienke, is a Delphi IDE plugin that runs your tests automatically in the background and shows results right in the editor gutter — green dots for passing tests, red dots for failures. When you save a file, tests re-run instantly. It is the closest thing Delphi has to the “live test” experience of tools like NCrunch for .NET or Wallaby.js for JavaScript.

kbmUnitTest integrates with TestInsight through a single optional unit, kbmTestInsight.pas. The integration posts results in real time — each test result appears in the IDE the moment it finishes, rather than waiting for the entire suite to complete.

Prerequisites

1. TestInsight installed — Download and install from bitbucket.org/sglienke/testinsight. After installation, you will see a TestInsight panel in the IDE (View → TestInsight Explorer).
2. TestInsight source path — The installer places source files (including TestInsight.Client.pas) in a directory like C:\Users\<you>\AppData\Local\Programs\TestInsight\Source. This path must be on your project’s search path so that kbmTestInsight.pas can find the TestInsight.Client unit it uses in its implementation section. Add it via Project → Options → Delphi Compiler → Search Path. The TestInsight client communicates with the IDE over HTTP using Indy (IdHTTP), which ships with Delphi — no extra installation is needed for that.
3. kbmTestInsight.pas — Copy this file alongside the other framework units in your library path.

Quick-start shortcut. Instead of adding the search path manually, you can right-click your project in the Project Manager and select TestInsight Project. This adds the TESTINSIGHT conditional define and the TestInsight source path in one step.

Setting Up Your Test Project

The key change is in your DPR file. You use a conditional define to switch between TestInsight mode (for the IDE) and normal console mode (for CI or command-line execution):

program MyTests;
{$APPTYPE CONSOLE}
{$STRONGLINKTYPES ON}
uses
  kbmTestFramework,
  kbmTestRunner,
  kbmTestInsight,       // <-- add this
  Test.Calculator in 'Test.Calculator.pas';
begin
  {$IFDEF TESTINSIGHT}
  RunTestInsight;
  {$ELSE}
  RunTests;
  {$ENDIF}
end.

Now add the conditional define:

1. Open Project → Options → Delphi Compiler → Conditional Defines.
2. Add TESTINSIGHT to the list.

When you run from the IDE, TESTINSIGHT is defined and RunTestInsight takes over. When you build for CI (where the define is not set), the project falls back to RunTests or RunTestsForCI.

How RunTestInsight Works

RunTestInsight performs the following steps:

1. Creates a TTestInsightRestClient (the concrete implementation of ITestInsightClient) which immediately attempts to connect to the TestInsight server running inside the IDE.
2. If the server is not found (HasError returns True — for example, you are running from the command line without the IDE), it falls back to RunTestsAndHalt automatically — no code changes needed.
3. Queries TestInsight for which tests to run. If the user has selected specific tests in the TestInsight Explorer, only those are executed. If none are selected, all tests run.
4. Creates a TkbmTestRunner, attaches a TkbmTestInsightLogger, and executes.
5. Each result is posted to the IDE in real time via ITestInsightClient.PostResult.

Memory leak detection is enabled by default in TestInsight mode (with lrmWarning — leaks are reported but do not fail the test). This gives you visibility into leaks during development without interrupting your flow.

The Developer Workflow

Once configured, the workflow is:

1. Open your test project in the IDE.
2. Open the TestInsight Explorer panel (View → TestInsight Explorer).
3. Press Run (or let the automatic run trigger on save).
4. Watch the gutter in your test source: green dots appear next to passing tests, red dots next to failures.
5. Click a red dot to see the failure message.
6. Fix the code, save, tests re-run automatically.

This tight feedback loop is transformative for test-driven development. You spend less time context-switching between the editor and a console window, and failures surface within seconds of introducing them.

Combining TestInsight with Other Loggers

If you need to, you can create the runner manually for finer control. This requires adding TestInsight.Client to your uses clause directly (the standard RunTestInsight path handles this internally):

procedure RunTestInsightCustom;
var
  LClient: ITestInsightClient;
  LRunner: TkbmTestRunner;
begin
  LClient := TTestInsightRestClient.Create;
  if LClient.HasError then
  begin
    RunTestsAndHalt;
    Exit;
  end;
  LRunner := TkbmTestRunner.Create;
  try
    // TestInsight logger for IDE integration
    LRunner.AddLogger(TkbmTestInsightLogger.Create(LClient));
    // Also log to console (useful when watching the output pane)
    LRunner.AddLogger(TkbmConsoleTestLogger.Create(False));
    LRunner.DetectMemoryLeaks := True;
    LRunner.LeakReportMode := lrmWarning;
    LRunner.Execute;
  finally
    LRunner.Free;
  end;
  // LClient is an interface reference — released automatically
end;

The runner supports any number of loggers attached simultaneously. Each logger receives every event — begin run, begin fixture, test result, end fixture, end run — so they all stay in sync.

Tips for TestInsight Usage

Define management. Some developers prefer to enable TESTINSIGHT only in the Debug build configuration. This way Release builds and CI builds never accidentally route through TestInsight:

• Debug configuration: TESTINSIGHT defined.
• Release / CI configuration: no TESTINSIGHT.

Selective test execution. In the TestInsight Explorer you can right-click a fixture or individual test and choose “Run Selected”. Only those tests execute, making the feedback loop even faster when you are focused on a specific area.

Leak reporting. When a test leaks memory, the leak information (byte count and, if FastMM5 is active, class names) is included in the TestInsight result message. Hover over the test in the explorer to see the details.

Summary

Adding TestInsight integration is a small change:

1. Ensure the TestInsight source path (e.g. C:\Users\<you>\AppData\Local\Programs\TestInsight\Source) is on your project’s search path — or right-click the project and choose TestInsight Project to set it up automatically.
2. Add kbmTestInsight to uses.
3. Call RunTestInsight inside an {$IFDEF TESTINSIGHT} block.
4. Add the TESTINSIGHT conditional define to your Debug configuration.

You get instant in-editor feedback, automatic re-runs on save, and a seamless fallback to console mode for CI. In Part 3 we will explore the framework’s advanced testing features: the fluent API, custom constraints, parameterized tests, categories, TDataSet assertions, and memory leak detection.