OpenParable
Skip to content
← Back to skills

Horse Integration Tests

Testing & Quality
horse-integration-tests

Horse Integration Tests is an Agent Skill for testing & quality published in the HashLoad/horse repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guide for writing automated integration tests for Horse endpoints using DUnit/DUnitX and THTTPClient.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/HashLoad/horse/blob/HEAD/doc/skills/horse-integration-tests/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/horse-integration-tests, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Horse Integration Testing

Automated integration tests ensure your API routes, request parsing, and error-handling pipelines behave correctly under simulated HTTP traffic.


1. The Dynamic Port Pattern

When running tests locally or in CI/CD pipelines (like GitHub Actions), static ports (e.g., 9000) might be occupied. To avoid port conflicts:

  1. Generate a dynamic port for each test run.
  2. Start Horse on that port inside the setup method.
  3. Perform HTTP requests against http://localhost:<dynamic_port>.
  4. Terminate Horse inside the teardown method.

2. Integration Test Example (DUnitX)

Here is a complete integration test suite demonstrating how to bootstrap Horse, perform requests with Delphi's native THTTPClient, and assert responses:

unit Test.UserAPI;

interface

uses
  DUnitX.TestFramework,
  System.Net.HttpClient,
  System.SysUtils;

type
  [TestFixture]
  TTestUserAPI = class
  private
    FPort: Integer;
    FClient: THTTPClient;
    function GetBaseURL: string;
  public
    [SetupFixture]
    procedure SetupFixture; // Start Horse Server
    [TearDownFixture]
    procedure TearDownFixture; // Terminate Horse Server
    [Setup]
    procedure Setup;
    [TearDown]
    procedure TearDown;
    
    [Test]
    procedure TestGetPingReturnsPong;
    [Test]
    procedure TestGetInvalidUserReturns404;
  end;

implementation

uses
  Horse,
  System.JSON,
  System.Net.URLClient;

function TTestUserAPI.GetBaseURL: string;
begin
  Result := 'http://localhost:' + FPort.ToString;
end;

procedure TTestUserAPI.SetupFixture;
begin
  // Choose a random dynamic port
  Randomize;
  FPort := 10000 + Random(50000);
  
  // Register endpoints to test
  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      Res.Send('pong');
    end);

  THorse.Get('/users/:id',
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    var
      LId: Integer;
    begin
      LId := Req.Params.Field('id').AsInteger;
      if LId = 999 then
        Res.Status(THTTPStatus.NotFound).Send('User not found')
      else
        Res.Send('User found');
    end);

  // Start Horse asynchronously (non-blocking)
  THorse.Listen(FPort);
end;

procedure TTestUserAPI.TearDownFixture;
begin
  // Terminate the process / stop Horse provider
  THorse.Terminate;
end;

procedure TTestUserAPI.Setup;
begin
  FClient := THTTPClient.Create;
end;

procedure TTestUserAPI.TearDown;
begin
  FClient.Free;
end;

procedure TTestUserAPI.TestGetPingReturnsPong;
var
  LResponse: IHTTPResponse;
begin
  LResponse := FClient.Get(GetBaseURL + '/ping');
  
  Assert.AreEqual(200, LResponse.StatusCode);
  Assert.AreEqual('pong', LResponse.ContentAsString);
end;

procedure TTestUserAPI.TestGetInvalidUserReturns404;
var
  LResponse: IHTTPResponse;
begin
  LResponse := FClient.Get(GetBaseURL + '/users/999');
  
  Assert.AreEqual(404, LResponse.StatusCode);
  Assert.AreEqual('User not found', LResponse.ContentAsString);
end;

initialization
  TDUnitX.RegisterTestFixture(TTestUserAPI);
end.

3. Best Practices for Integration Testing

  1. Isolate Database State: Before running tests, mock database tables or use transactional rollbacks to ensure tests start with clean, predictable data.
  2. Separate Test Logic: Keep your route handlers in dedicated Controller units. Do not define routes inline in your test project setup unless you are testing general configuration middleware behavior.
  3. Always call THorse.Terminate: Failing to call Terminate in your tear down fixture will leave the TCP socket open, preventing subsequent test executions from binding to the same port.