testbox-mockbox

Create and manage mocks, stubs, and spies for TestBox unit tests in ColdBox applications.

1|Updated Apr 10, 2026
One-click install
npx skills add https://github.com/ColdBox/skills --skill testbox-mockbox
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: testbox-mockbox
Source: https://github.com/ColdBox/skills/tree/main/testbox/mockbox
Command: npx skills add https://github.com/ColdBox/skills --skill testbox-mockbox

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Provide deterministic, controllable test doubles for ColdBox TestBox specs so unit tests can isolate systems under test, simulate database queries, and assert interactions without hitting real external services.

Core Features & Use Cases

  • Full, empty, and partial mocks via createMock, createEmptyMock, and prepareMock to replace collaborators and drive specific behaviors.
  • Argument-specific stubbing with $args and $results, exception simulation with $throws, query simulation with querySim, property injection with $property, and spying on real methods with $spy for behavioral verification.
  • Call logging and verification helpers ($once, $never, $times, $count, $callLog) to assert invocation counts and inspect arguments in service, DAO, and email-sending scenarios.

Quick Start

Prepare a mock for UserService that stubs save to return an object with id 1 and assert that save was called once.

Frequently Asked Questions about testbox-mockbox

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create mocks and stubs for TestBox unit tests in ColdBox?

To stub specific method behaviors in TestBox, use $args() to match method arguments and $results() to define sequential return values, allowing precise control over mock responses during unit test execution.

How do I simulate database queries in TestBox specs?

You simulate database queries in TestBox specs by using the querySim() function, which generates mock query objects to avoid hitting real external database services during unit test execution.

How do I verify method calls and arguments in ColdBox mocks?

You verify method calls and arguments in ColdBox mocks by using call logging and verification helpers like $once, $never, $times, $count, and $callLog to assert invocation counts and inspect passed arguments.

What is the difference between a full mock and a partial mock in TestBox?

A full mock via createMock replaces an entire object, an empty mock via createEmptyMock strips existing behavior, and a partial mock via prepareMock allows spying on real methods while stubbing only specific collaborators.

Can I inject properties into a ColdBox mock during unit testing?

Yes, you can inject properties into a ColdBox mock during unit testing by using the $property() function to set internal variables, enabling deterministic state control without relying on real initialization processes.

How do I spy on real methods in TestBox without stopping their execution?

You spy on real methods in TestBox by using the $spy() function, which allows behavioral verification by recording method calls and arguments while still executing the actual underlying method logic.