🧪 DevLog: Integrated Unit Testing Framework - Test-Driven Development Arrives in JetPascal!

[jarroddavis68]

Version: JetPascal 0.2.0+

📢 Overview

JetPascal now has built-in unit testing directly integrated into the language! Write tests alongside your code, run them automatically, and get instant feedback - all without external dependencies or frameworks.

This is a game-changer for:

• Test-Driven Development (TDD) in Pascal
• Regression testing for libraries
• CI/CD integration with proper exit codes
• Confidence in refactoring with test coverage
• Professional software development practices

🎯 Why Built-In Unit Testing?

The Problem

Traditional Pascal testing meant:

• ❌ Installing separate testing frameworks (DUnit, FPCUnit, etc.)
• ❌ Learning framework-specific syntax and setup
• ❌ Configuring test runners and harnesses
• ❌ Maintaining separate test projects
• ❌ Complex build configurations

The Solution

JetPascal makes testing effortless:

program MathTest;

UNITTESTMODE ON;

function Add(const A: Integer; const B: Integer): Integer;
begin
  Result := A + B;
end;

begin
  WriteLn('Program runs normally');
end.

test 'Add function works correctly'
begin
  Check(Add(2, 3) = 5);
  CheckEqual(5, Add(2, 3));
end;

That's it.

✅ No external dependencies - Built into the language
✅ No framework installation - Just UNITTESTMODE ON
✅ No separate test projects - Tests live with code
✅ No configuration - It just works
✅ Automatic test discovery - No registration needed
✅ Clean output - Professional test runner included

🔧 Core Features

UNITTESTMODE Directive

Enable/disable unit testing:

UNITTESTMODE ON;   // Enable test compilation
UNITTESTMODE OFF;  // Disable test compilation (default)

Key behaviors:

• When ON: Tests are compiled and run via dedicated test runner
• When OFF: Tests are completely excluded from compilation (zero overhead)
• Works in programs, libraries, and units
• Sets JETPASCAL_UNITTEST preprocessor define for conditional compilation

test Blocks

Define test cases:

test 'descriptive test name'
begin
  // Test code here
  Check(condition);
  CheckEqual(expected, actual);
end;

Features:

• Descriptive names using string literals
• Multiple tests per file
• Tests run automatically
• Failures don't stop execution (all tests run)
• Clear pass/fail reporting

Check() - Boolean Assertions

Verify conditions:

Check(condition);

Examples:

Check(Add(2, 3) = 5);              // Equality check
Check(IsEven(4));                  // Boolean function
Check(not IsOdd(4));               // Negation
Check(X > 0);                      // Comparison
Check(Length(MyArray) = 10);       // Array length

Output on failure:

CHECK FAILED at .\tests\MyTest.pas:42

CheckEqual() - Equality with Details

Compare values with detailed output:

CheckEqual(expected, actual);

Examples:

CheckEqual(5, Add(2, 3));              // Integer equality
CheckEqual(3.14, CalculatePi());       // Floating point
CheckEqual('Hello', GetGreeting());    // String equality
CheckEqual(42, MyFunction(7, 6));      // Function result

Output on failure:

CHECK FAILED at .\tests\MyTest.pas:42: expected 5, got 3

Why CheckEqual vs Check?

• Check() only tells you it failed
• CheckEqual() shows expected vs actual values
• Use CheckEqual() for better debugging experience

💻 Complete Working Example

Basic Program with Tests

Source: ProgramUnitTest.pas

program ProgramUnitTest;

UNITTESTMODE ON;

function Add(const A: Integer; const B: Integer): Integer;
begin
  Result := A + B;
end;

function Multiply(const A: Integer; const B: Integer): Integer;
begin
  Result := A * B;
end;

function IsEven(const A: Integer): Boolean;
begin
  Result := (A mod 2) = 0;
end;

begin
  WriteLn('MathTest Program - Functions defined');
end.

test 'Add function basic cases'
begin
  Check(Add(2, 3) = 5);
  Check(Add(0, 0) = 0);
  Check(Add(-5, 5) = 0);
  CheckEqual(10, Add(7, 3));
end;

test 'Add function edge cases'
begin
  CheckEqual(0, Add(-10, 10));
  CheckEqual(100, Add(50, 50));
  Check(Add(1, 1) = 2);
end;

test 'Multiply function'
begin
  CheckEqual(6, Multiply(2, 3));
  CheckEqual(0, Multiply(5, 0));
  CheckEqual(-20, Multiply(4, -5));
  Check(Multiply(3, 3) = 9);
end;

test 'IsEven function'
begin
  Check(IsEven(2));
  Check(IsEven(0));
  Check(IsEven(100));
  Check(not IsEven(1));
  Check(not IsEven(3));
  Check(not IsEven(-7));
end;

test 'Complex expression'
begin
  Check(Add(2, 3) + Multiply(4, 5) = 25);
  CheckEqual(25, Add(2, 3) + Multiply(4, 5));
end;

Test Output

Output:

JetPascal Unit Test Runner

Running: Add function basic cases ... PASSED
Running: Add function edge cases ... PASSED
Running: Multiply function ... PASSED
Running: IsEven function ... PASSED
Running: Complex expression ... PASSED

All tests PASSED

Exit code: 0 (success)

When Tests Fail

Modified test (intentionally wrong):

test 'Add function basic cases'
begin
  Check(Add(2, 3) = 5);
  CheckEqual(11, Add(7, 3));  // WRONG: should be 10
end;

Output:

JetPascal Unit Test Runner

Running: Add function basic cases ... CHECK FAILED at .\tests\ProgramUnitTest.pas:28: expected 11, got 10
FAILED
Running: Add function edge cases ... PASSED
Running: Multiply function ... PASSED
Running: IsEven function ... PASSED
Running: Complex expression ... PASSED

1 test(s) FAILED

Exit code: 1 (failure)

Perfect for CI/CD! The exit code tells your build system exactly what happened.

📍 Where Tests Can Live

Programs (Full Test Support)

program MyApp;

UNITTESTMODE ON;

// Functions to test
function Calculate(const X: Integer): Integer;
begin
  Result := X * 2;
end;

// Normal program code
begin
  WriteLn('Application running');
end.

// Tests appear after program end
test 'Calculate doubles input'
begin
  CheckEqual(4, Calculate(2));
  CheckEqual(10, Calculate(5));
end;

Behavior:

• Normal mode: Runs program logic (WriteLn executes)
• Test mode: Replaces main() with test runner
• All tests run automatically

Libraries (Test Support)

library MyLib;

UNITTESTMODE ON;

function LibraryAdd(const A: Integer; const B: Integer): Integer; cdecl;
begin
  Result := A + B;
end;

exports
  LibraryAdd;

begin
end.

test 'Library function'
begin
  CheckEqual(5, LibraryAdd(2, 3));
end;

Behavior:

• Normal mode: Builds as shared library (.dll/.so)
• Test mode: Tests are registered but no main() generated
• Tests can be run by a test harness

Units (Test Support)

unit MathUtils;

UNITTESTMODE ON;

interface

function Square(const X: Integer): Integer;

implementation

function Square(const X: Integer): Integer;
begin
  Result := X * X;
end;

end.

test 'Square function'
begin
  CheckEqual(4, Square(2));
  CheckEqual(9, Square(3));
  CheckEqual(0, Square(0));
end;

Behavior:

• Normal mode: Builds as static library (.a/.lib)
• Test mode: Tests registered, no main() generated
• Units can be tested independently

🏗️ How It Works Under the Hood

Architecture: Compiler Integration

JetPascal's test framework is deeply integrated into the compiler architecture:

Pascal Source
     ↓
Parse test blocks (TTestBlockToken)
     ↓
Register tests (TCompiler.RegisterTest)
     ↓
Generate C++ test functions
     ↓
Emit test infrastructure (runner, registry)
     ↓
Compile with #ifdef JETPASCAL_UNITTEST guards
     ↓
Native Executable

Token-Based Implementation

Each test construct is a SmartToken:

TUnittestModeToken    // UNITTESTMODE ON/OFF
TTestBlockToken       // test 'name' begin...end;
TCheckToken           // Check(condition)
TCheckEqualToken      // CheckEqual(expected, actual)

Token architecture benefits:

• Clean separation of concerns
• Easy to extend with new assertions
• Follows JetPascal's polymorphic design
• Type-safe parsing and code generation

Generated C++ Code

Pascal test:

test 'Add function'
begin
  Check(Add(2, 3) = 5);
  CheckEqual(10, Add(7, 3));
end;

Generated C++ (simplified):

#ifdef JETPASCAL_UNITTEST

inline thread_local bool test_failed = false;

void test_Add_function() {
  if (!(Add(2, 3) == 5)) {
    test_failed = true;
    std::println(stderr, "CHECK FAILED at .\\tests\\MyTest.pas:26");
  }
  if (10 != Add(7, 3)) {
    test_failed = true;
    std::println(stderr, "CHECK FAILED at .\\tests\\MyTest.pas:27: expected 10, got {}", Add(7, 3));
  }
}

struct TestCase {
  std::string_view name;
  void (*func)();
};

constexpr std::array g_MyTest_tests = {
  TestCase{"Add function", test_Add_function},
};

int MyTest_run_tests() {
  int passed = 0, failed = 0;
  
  for (const auto& test : g_MyTest_tests) {
    test_failed = false;
    std::print("Running: {} ... ", test.name);
    test.func();
    
    if (test_failed) {
      std::println("FAILED");
      failed++;
    } else {
      std::println("PASSED");
      passed++;
    }
  }
  
  return failed;
}

int main() {
  std::println("JetPascal Unit Test Runner\\n");
  
  int total_failed = 0;
  total_failed += MyTest_run_tests();
  
  std::println();
  if (total_failed > 0) {
    std::println("{} test(s) FAILED", total_failed);
    return 1;
  } else {
    std::println("All tests PASSED");
    return 0;
  }
}

#endif // JETPASCAL_UNITTEST

Key implementation details:

• ✅ Thread-local flag - Each test tracks its own failure state
• ✅ Test registry - Compile-time array of test functions
• ✅ Automatic runner - No manual test registration needed
• ✅ Clean guards - All test code behind #ifdef for zero overhead
• ✅ File/line info - Precise error locations via #line directives

Conditional Compilation

Normal build (UNITTESTMODE OFF):

// Program's normal main() function
int main(int argc, char* argv[]) {
  jp::internal::SetCommandLine(argc, argv);
  jp::internal::InitializeConsole();
  
  std::println("Application running");
  
  return 0;
}

// Test code completely excluded (not even compiled!)

Test build (UNITTESTMODE ON):

// Program's main() excluded
#ifndef JETPASCAL_UNITTEST
int main(int argc, char* argv[]) {
  // ... normal code
}
#endif

// Test infrastructure included
#ifdef JETPASCAL_UNITTEST
inline thread_local bool test_failed = false;

void test_Add_function() { /* ... */ }

int main() {
  // Test runner replaces program main
  std::println("JetPascal Unit Test Runner");
  // ...
}
#endif

Result: Binary contains either program OR tests, never both!

🎨 Design Philosophy

DUnit Compatibility

JetPascal's test syntax is inspired by DUnit, Delphi's classic unit testing framework:

DUnit (traditional):

procedure TMyTests.TestAdd;
begin
  CheckEquals(5, Add(2, 3));
  CheckTrue(IsEven(4));
end;

JetPascal:

test 'Add function'
begin
  CheckEqual(5, Add(2, 3));
  Check(IsEven(4));
end;

Why this naming?

• ✅ Familiar to Delphi developers
• ✅ Check clearly indicates testing (not runtime assertions)
• ✅ No conflict with Pascal's built-in Assert
• ✅ Room to grow: CheckTrue, CheckFalse, CheckNotEqual, etc.

Work Smart, Not Hard

Following JetPascal's philosophy:

• Leverage C++ - Use std::println for output, not custom formatting
• Use compiler - #ifdef guards, compile-time test registry
• Zero overhead - Tests completely excluded when disabled
• Automatic discovery - No manual registration needed

Test-Driven Development (TDD)

JetPascal's testing enables proper TDD workflow:

Red → Green → Refactor

1. Red: Write failing test

test 'Calculate average'
begin
  CheckEqual(5, Average([3, 5, 7]));
end;

2. Green: Implement function

function Average(const AValues: array of Integer): Integer;
var
  LSum: Integer;
  LValue: Integer;
begin
  LSum := 0;
  for LValue in AValues do
    LSum := LSum + LValue;
  Result := LSum div Length(AValues);
end;

3. Refactor: Improve with confidence

// Refactor knowing tests will catch regressions
function Average(const AValues: array of Integer): Integer;
begin
  Result := Sum(AValues) div Length(AValues);
end;

💡 Best Practices

DO:

✅ Write descriptive test names - 'Add handles negative numbers' not just 'Test 1'
✅ Test one thing per test - Focused tests are easier to debug
✅ Use CheckEqual for comparisons - Better error messages than Check
✅ Test edge cases - Zero, negative, empty, null, boundary values
✅ Keep tests simple - Tests should be easier to understand than code
✅ Run tests frequently - After every change, catch regressions early

DON'T:

❌ Don't test implementation details - Test behavior, not internals
❌ Don't make tests depend on each other - Each test must be independent
❌ Don't skip edge case testing - Edge cases find the most bugs
❌ Don't use Check for equality - Use CheckEqual for better diagnostics
❌ Don't write flaky tests - Tests must be deterministic

🎓 Advanced Techniques

Technique 1: Testing Private Functions

Problem: Need to test internal helper functions

Solution: Use conditional compilation

function InternalHelper(const X: Integer): Integer;
begin
  Result := X * 2;
end;

// In normal build, this is private
// In test build, we can test it!

test 'Internal helper'
begin
  CheckEqual(4, InternalHelper(2));
end;

Technique 2: Test Data Setup

test 'Complex calculation'
begin
  // Arrange
  var LInput: Integer := 42;
  var LExpected: Integer := 84;
  
  // Act
  var LActual: Integer := Calculate(LInput);
  
  // Assert
  CheckEqual(LExpected, LActual);
end;

Technique 3: Multiple Assertions

test 'Function properties'
begin
  // Test multiple aspects of same function
  CheckEqual(0, Square(0));      // Zero case
  CheckEqual(1, Square(1));      // Identity
  CheckEqual(4, Square(-2));     // Negative
  CheckEqual(100, Square(10));   // Positive
  
  // All assertions run even if earlier ones fail!
end;

Technique 4: Testing Boolean Functions

test 'IsEven function'
begin
  // Positive cases
  Check(IsEven(0));
  Check(IsEven(2));
  Check(IsEven(100));
  
  // Negative cases
  Check(not IsEven(1));
  Check(not IsEven(3));
  Check(not IsEven(-7));
end;

Technique 5: Complex Expression Testing

test 'Expression evaluation'
begin
  // Test entire expression, not just individual functions
  Check(Add(2, 3) + Multiply(4, 5) = 25);
  
  // Also test with CheckEqual for better errors
  CheckEqual(25, Add(2, 3) + Multiply(4, 5));
end;

🔄 Integration with Build Systems

Exit Codes for CI/CD

Perfect for automated testing:

#!/bin/bash
jetpascal build MyTests.pas
./MyTests
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "✅ All tests passed"
  exit 0
else
  echo "❌ Tests failed"
  exit 1
fi

GitHub Actions Example

name: Run Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Build tests
        run: jetpascal build tests/AllTests.pas
      
      - name: Run tests
        run: ./tests/AllTests

Test failure automatically fails the build!

Build System Detection

JetPascal automatically adds test defines to build.zig:

// When UNITTESTMODE ON
exe.defineCMacro("JETPASCAL_UNITTEST", "1");

This ensures the C++ compiler sees the correct flags!

📊 Performance Impact

Compilation Time:

• Test parsing: Negligible (< 1ms per test)
• Test code generation: Fast (native C++ output)
• Overall: Same speed as normal compilation

Runtime Performance:

• Normal build: Zero overhead (tests excluded entirely)
• Test build: Near-native speed (compiled C++, no interpretation)
• Test runner overhead: < 1ms (simple loop + output)

Binary Size:

• Normal build: Zero increase (no test code)
• Test build: Small increase (only test functions + runner)

🚦 Current Status & Future Plans

✅ Fully Implemented

• UNITTESTMODE ON/OFF directive
• test 'name' begin...end; blocks
• Check(condition) assertions
• CheckEqual(expected, actual) assertions
• Automatic test discovery
• Automatic test runner generation
• File/line error reporting
• CI/CD-friendly exit codes
• Works in programs, libraries, units

🚧 Coming Soon (Phase 2)

• CheckTrue(condition) - Explicit true check
• CheckFalse(condition) - Explicit false check
• CheckNotEqual(exp, act) - Inequality check
• CheckGreater(exp, act) - Greater-than check
• CheckLess(exp, act) - Less-than check
• CheckGreaterOrEqual(exp, act) - ≥ check
• CheckLessOrEqual(exp, act) - ≤ check
• CheckNull(pointer) - Null pointer check
• CheckNotNull(pointer) - Non-null pointer check
• Test setup/teardown blocks
• Test suites and categories
• Benchmark/performance testing
• Custom failure messages

💡 Future Possibilities

• Exception testing: CheckRaises(MyFunc, EMyException)
• Floating-point comparison: CheckEqual(exp, act, epsilon)
• String matching: CheckContains(haystack, needle)
• Collection testing: CheckCount(list, 5)
• Mock/stub support for dependency injection
• Code coverage reporting integration

🤔 Technical Q&A

Q: How is this different from DUnit?
A: DUnit is an external framework requiring installation. JetPascal's tests are built into the language - no dependencies, no setup, just code.

Q: Can I use both Assert and Check?
A: Yes, but they behave differently! Pascal's Assert raises exceptions (stops execution). JetPascal's Check sets flags (all tests run). Use Check for testing.

Q: What about FPCUnit or other frameworks?
A: You can still use those! But JetPascal's built-in testing is simpler for most cases and has zero dependencies.

Q: Can I test existing Delphi code?
A: Yes! JetPascal compiles Delphi-compatible Pascal. Add UNITTESTMODE ON and test blocks - your existing code works as-is.

Q: Does this work with cross-compilation?
A: Absolutely! Tests compile and run on any target platform (Windows, Linux, macOS, etc.)

Q: How do I test private/internal functions?
A: In test mode, they're accessible! The #ifdef JETPASCAL_UNITTEST guards give tests access to everything.

Q: Can I test libraries without a main program?
A: Libraries and units register tests but don't generate a runner. You can create a separate test program that uses the library.

Q: What about GUI testing?
A: Current tests are for logic/algorithms. GUI testing frameworks (like VCL testers) would be separate - this tests pure functions.

🎬 Real-World Use Case: Raylib Wrapper Testing

Scenario: Testing a JetPascal raylib wrapper

unit RaylibWrapper;

UNITTESTMODE ON;

interface

function ColorToInt(const R: Byte; const G: Byte; const B: Byte): Integer;
function IntToColor(const AColor: Integer): record R, G, B: Byte end;

implementation

function ColorToInt(const R: Byte; const G: Byte; const B: Byte): Integer;
begin
  Result := (R shl 16) or (G shl 8) or B;
end;

function IntToColor(const AColor: Integer): record R, G, B: Byte end;
begin
  Result.R := (AColor shr 16) and $FF;
  Result.G := (AColor shr 8) and $FF;
  Result.B := AColor and $FF;
end;

end.

test 'Color conversion'
begin
  // Test RGB to int
  CheckEqual($FF0000, ColorToInt(255, 0, 0));    // Red
  CheckEqual($00FF00, ColorToInt(0, 255, 0));    // Green
  CheckEqual($0000FF, ColorToInt(0, 0, 255));    // Blue
  CheckEqual($FFFFFF, ColorToInt(255, 255, 255)); // White
  
  // Test int to RGB
  var LColor := IntToColor($FF0000);
  CheckEqual(255, LColor.R);
  CheckEqual(0, LColor.G);
  CheckEqual(0, LColor.B);
end;

test 'Color roundtrip'
begin
  // Ensure converting back and forth preserves values
  var LOriginal := $12ABCD;
  var LColor := IntToColor(LOriginal);
  var LConverted := ColorToInt(LColor.R, LColor.G, LColor.B);
  CheckEqual(LOriginal, LConverted);
end;

Benefits:

• ✅ Test helper functions independently
• ✅ Verify data conversion correctness
• ✅ Catch regressions during refactoring
• ✅ Document expected behavior via tests

🎉 Success Stories

Before JetPascal Testing

Developer workflow:

1. Write code
2. Manually test in console
3. Pray nothing breaks
4. Ship and hope
5. Bug reports arrive
6. Debug in production
7. Repeat

After JetPascal Testing

Developer workflow:

1. Write test (red)
2. Write code (green)
3. Refactor (tests catch issues)
4. Run tests (all pass)
5. Ship with confidence
6. Sleep well

🙏 Acknowledgments

This feature wouldn't exist without:

• DUnit - Inspiration for test syntax and naming
• Google Test (C++) - Architecture ideas for test runners
• JUnit (Java) - Patterns for assertion methods
• Community feedback - Thanks for requesting testing support!
• Claude AI - Architectural discussions and implementation

📝 Closing Thoughts

Built-in unit testing represents a major milestone for JetPascal. It's not just about testing - it's about confidence. Confidence to refactor. Confidence to add features. Confidence that your code works.

The beauty of JetPascal's approach:

• Zero setup - No frameworks to install
• Zero dependencies - Built into the language
• Zero overhead - Tests excluded in normal builds
• 100% Pascal - Clean, readable syntax

Testing is no longer optional. It's effortless.

🚀 Try It Out!

Create test project:

jet init FirstTest -t program

Edit a test file:

program FirstTest;

UNITTESTMODE ON;

function DoubleValue(const X: Integer): Integer;
begin
  Result := X * 2;
end;

begin
  WriteLn('Normal program logic');
end.

test 'Double function'
begin
  CheckEqual(4, DoubleValue(2));
  CheckEqual(10, DoubleValue(5));
  CheckEqual(0, DoubleValue(0));
  CheckEqual(-4, DoubleValue(-2));
end;

Build and test:

jet build
jet run

Output:

JetPascal Unit Test Runner

Running: Double function ... PASSED

All tests PASSED

Congratulations! You just wrote your first JetPascal unit test! 🎉

---

Have questions or cool test examples? Drop them in the comments! We'd love to hear how you're using unit testing in your JetPascal projects.

Happy Testing! 🧪

JetPascal™ - Accelerate Your Code!