ApexBlueprint Developer Guide
ApexBlueprint is an OSS for integration test data generation — assembling parent-child record groups in dependency order and inserting them via DML. This guide is structured in four tiers: Setup (prerequisites and installation), Usage Guides (how to use it in test code), API Reference (full method signatures), and Deep Dives (the philosophy behind the design).
Setup
The path from environment setup to deploying ApexBlueprint to your org.
Prerequisites
Confirm the four setup steps before installing ApexBlueprint: Salesforce CLI, target org, default org configuration, and the make command.
Installation Guide
A walkthrough for installing ApexBlueprint in a Salesforce project: acquiring it via Git Submodule, deploying with make install, and updating it later.
Usage Guides
Typical scenarios for using SBlueprint and SOrchestrator in integration tests, in the order: single record → execution engine → relations and bulk patterns.
Declaring a Single Record with SBlueprint
The five core SBlueprint methods (of / set / template / alias / use) for assembling test data, explained alongside the idea of "declaring the final shape of the data".
Resolving Dependencies and Executing DML with SOrchestrator
The four SOrchestrator methods (start / add / create / getByAlias) that turn blueprints into real records, plus pitfalls such as topological sort, circular dependencies, and alias duplication.
Relations, Bulk Generation, and Reference Patterns
Advanced patterns built on top of single-record declarations: withChildren nesting, bulk generation with times + {#}, use offsets, true-parent resolution with {P0} / {P1}, and lookup disambiguation with parentIdField.
API Reference
Detailed reference for each class, covering every API with signatures.
SBlueprint
Full API reference for the SBlueprint method chain: factory, value setters, alias, use, times, withChildren, parentIdField, and the {#} / {A} / {a} / {P0}~{Pn} placeholder semantics.
SOrchestrator
Full API reference for the SOrchestrator execution engine: factory (with MockDmlOperator injection), add / create / getByAlias, and the exceptions raised on circular references, duplicate aliases, invalid references, and ambiguous lookups.
Deep Dives
Long-form pieces exploring why ApexBlueprint settled on this form.
Declarative Data Specification: Why the Blueprint Form?
A deep dive into the design philosophy. The structural fatigue of procedural test data factories (ID bucket relay, method explosion, opaque final shapes, redundant records), the shift to "declaring the final shape of data", and why this matters especially in Salesforce.
Dependency Resolution Internals: Topological Sort + Alias Resolution
A phase-by-phase walkthrough of SOrchestrator.create() internals. How circular-dependency detection, automatic aliasing, and the {P0} / {P1} hierarchical resolution are unified into one pipeline, with references to actual implementation files.
What to Read Next
- Test Strategy: Where
SBlueprint/SOrchestratorfit in Handler integration testing - Apex Stem Introduction Guide: A 4-step walkthrough with working code
- ApexBlueprint on GitHub: Source code and latest updates