feat: add TestBox tests and docs for query builder (#1908)

Replace RocketUnit tests with TestBox BDD specs for QueryBuilder including
where, orWhere, whereNull, whereBetween, whereIn, orderBy, limit, and
terminal methods. Add shared test infrastructure.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bpamiri

CHANGELOG.md

@@ -18,6 +18,13 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ----
 
+## [Unreleased]
+
+### Added
+- Chainable query builder with `where()`, `orWhere()`, `whereNull()`, `whereBetween()`, `whereIn()`, `orderBy()`, `limit()`, and more for injection-safe fluent queries
+
+----
+
 
 # [3.0.0](https://github.com/wheels-dev/wheels/releases/tag/v3.0.0) => 2026-01-10
 

docs/src/SUMMARY.md

@@ -177,6 +177,7 @@
 * [Transactions](database-interaction-through-models/transactions.md)
 * [Dirty Records](database-interaction-through-models/dirty-records.md)
 * [Soft Delete](database-interaction-through-models/soft-delete.md)
+* [Query Builder](database-interaction-through-models/query-builder.md)
 * [Automatic Time Stamps](database-interaction-through-models/automatic-time-stamps.md)
 * [Database Migrations](database-interaction-through-models/database-migrations/README.md)
   * [Migrations in Production](database-interaction-through-models/database-migrations/migrations-in-production.md)

docs/src/database-interaction-through-models/query-builder.md

@@ -0,0 +1,160 @@
+# Query Builder
+
+The query builder provides a fluent, chainable API for constructing database queries. It is an alternative to passing raw SQL strings to `findAll(where="...")`, with the added benefit of automatic value quoting for SQL injection safety.
+
+## Basic Usage
+
+Start a query chain by calling `.where()` on any model, then finish with a terminal method like `.get()`:
+
+```cfm
+users = model("User")
+    .where("status", "active")
+    .where("age", ">", 18)
+    .orderBy("name", "ASC")
+    .limit(25)
+    .get();
+```
+
+## WHERE Conditions
+
+### Equality
+
+```cfm
+// Two arguments: property, value
+model("User").where("status", "active").get();
+// Generates: status = 'active'
+```
+
+### Operators
+
+```cfm
+// Three arguments: property, operator, value
+model("User").where("age", ">", 18).get();
+model("User").where("views", ">=", 100).get();
+model("User").where("name", "LIKE", "%smith%").get();
+```
+
+### Raw Strings
+
+```cfm
+// One argument: raw WHERE clause (no auto-quoting)
+model("User").where("status = 'active' AND role = 'admin'").get();
+```
+
+### OR Conditions
+
+```cfm
+model("User")
+    .where("role", "admin")
+    .orWhere("role", "superadmin")
+    .get();
+// Generates: role = 'admin' OR role = 'superadmin'
+```
+
+### NULL Checks
+
+```cfm
+model("User").whereNull("deletedAt").get();
+model("User").whereNotNull("emailVerifiedAt").get();
+```
+
+### BETWEEN
+
+```cfm
+model("Product").whereBetween("price", 10, 50).get();
+// Generates: price BETWEEN 10 AND 50
+```
+
+### IN / NOT IN
+
+```cfm
+// With a comma-delimited list
+model("User").whereIn("role", "admin,editor,author").get();
+
+// With an array
+model("User").whereIn("role", ["admin", "editor"]).get();
+
+// NOT IN
+model("User").whereNotIn("status", "banned,suspended").get();
+```
+
+## Ordering
+
+```cfm
+model("User").orderBy("name", "ASC").get();
+model("User").orderBy("createdAt", "DESC").get();
+
+// Multiple order clauses
+model("User")
+    .orderBy("lastName", "ASC")
+    .orderBy("firstName", "ASC")
+    .get();
+```
+
+## Limiting Results
+
+```cfm
+model("User").limit(10).get();
+model("User").offset(20).limit(10).get();
+```
+
+## Other Builder Methods
+
+```cfm
+// Select specific columns
+model("User").select("id,name,email").get();
+
+// Include associations
+model("User").include("profile,orders").get();
+
+// Group by
+model("Order").select("status,COUNT(id) as orderCount").group("status").get();
+
+// Distinct
+model("User").select("city").distinct().get();
+```
+
+## Terminal Methods
+
+Call one of these to execute the built query:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get()` | query | Alias for `findAll()` |
+| `findAll()` | query | All matching records |
+| `first()` | object | Alias for `findOne()` |
+| `findOne()` | object | First matching record |
+| `count()` | numeric | Number of matching records |
+| `exists()` | boolean | Whether any records match |
+| `updateAll(...)` | numeric | Update matching records |
+| `deleteAll()` | numeric | Delete matching records |
+| `findEach(callback)` | void | Batch iterate one at a time |
+| `findInBatches(callback)` | void | Batch iterate in groups |
+
+## Combining with Scopes
+
+You can transition from scopes to the query builder at any point in the chain:
+
+```cfm
+model("User")
+    .active()                    // scope
+    .where("role", "admin")      // query builder
+    .orderBy("name", "ASC")
+    .get();
+```
+
+See [Query Scopes](query-scopes.md) for defining reusable scope fragments.
+
+## SQL Injection Safety
+
+All values passed to `where()`, `whereBetween()`, `whereIn()`, and `whereNotIn()` are automatically quoted using the model's database adapter. You do not need to manually escape values:
+
+```cfm
+// Safe — value is auto-quoted
+model("User").where("name", userInput).get();
+
+// Also safe
+model("User").whereIn("id", userSuppliedIds).get();
+```
+
+Raw string WHERE clauses (single-argument `where()`) are passed through as-is. Avoid interpolating user input into raw strings.

tests/_assets/models/Author.cfc

@@ -0,0 +1,9 @@
+component extends="Model" {
+
+	function config() {
+		table("c_o_r_e_authors");
+		hasMany("posts");
+		hasOne("profile");
+	}
+
+}

tests/_assets/models/Post.cfc

@@ -0,0 +1,8 @@
+component extends="Model" {
+
+	function config() {
+		table("c_o_r_e_posts");
+		belongsTo("author");
+	}
+
+}

tests/populate.cfm

@@ -0,0 +1,75 @@
+<cfsetting requestTimeOut="300">
+<cfscript>
+// Get database info
+local.db_info = $dbinfo(datasource = application.wheels.dataSourceName, type = "version");
+local.db = LCase(Replace(local.db_info.database_productname, " ", "", "all"));
+
+// Set DB-specific types
+local.identityColumnType = "int NOT NULL IDENTITY";
+if (local.db IS "mysql" or local.db IS "mariadb") {
+	local.identityColumnType = "int NOT NULL AUTO_INCREMENT";
+} else if (local.db IS "postgresql") {
+	local.identityColumnType = "SERIAL NOT NULL";
+}
+local.storageEngine = (local.db IS "mysql" or local.db IS "mariadb") ? "ENGINE=InnoDB" : "";
+</cfscript>
+
+<!--- Drop existing tables --->
+<cftry>
+	<cfquery datasource="#application.wheels.dataSourceName#">DROP TABLE IF EXISTS c_o_r_e_posts</cfquery>
+	<cfcatch></cfcatch>
+</cftry>
+<cftry>
+	<cfquery datasource="#application.wheels.dataSourceName#">DROP TABLE IF EXISTS c_o_r_e_authors</cfquery>
+	<cfcatch></cfcatch>
+</cftry>
+
+<!--- Create tables --->
+<cfquery datasource="#application.wheels.dataSourceName#">
+CREATE TABLE c_o_r_e_authors (
+	id #local.identityColumnType#,
+	firstname varchar(100) NOT NULL,
+	lastname varchar(100) NOT NULL,
+	PRIMARY KEY(id)
+) #local.storageEngine#
+</cfquery>
+
+<cfquery datasource="#application.wheels.dataSourceName#">
+CREATE TABLE c_o_r_e_posts (
+	id #local.identityColumnType#,
+	authorid int NULL,
+	title varchar(250) NOT NULL,
+	body text NOT NULL,
+	createdat datetime NOT NULL,
+	updatedat datetime NOT NULL,
+	deletedat datetime NULL,
+	views int DEFAULT 0 NOT NULL,
+	averagerating float NULL,
+	status varchar(20) DEFAULT 'draft' NOT NULL,
+	PRIMARY KEY(id)
+) #local.storageEngine#
+</cfquery>
+
+<!--- Populate data --->
+<cfscript>
+model("author").create(firstName = "Per", lastName = "Djurner");
+model("author").create(firstName = "Tony", lastName = "Petruzzi");
+model("author").create(firstName = "Chris", lastName = "Peters");
+model("author").create(firstName = "Peter", lastName = "Amiri");
+model("author").create(firstName = "James", lastName = "Gibson");
+model("author").create(firstName = "Raul", lastName = "Riera");
+model("author").create(firstName = "Andy", lastName = "Bellenie");
+model("author").create(firstName = "Adam", lastName = "Chapman");
+model("author").create(firstName = "Tom", lastName = "King");
+model("author").create(firstName = "David", lastName = "Belanger");
+
+// Create posts with various statuses
+local.per = model("author").findOne(where = "firstName = 'Per'");
+local.per.createPost(title = "First post", body = "Body 1", views = 5, status = "published");
+local.per.createPost(title = "Second post", body = "Body 2", views = 5, status = "published");
+local.per.createPost(title = "Third post", body = "Body 3", views = 0, averageRating = "3.2", status = "archived");
+
+local.tony = model("author").findOne(where = "firstName = 'Tony'");
+local.tony.createPost(title = "Fourth post", body = "Body 4", views = 3, averageRating = "3.6", status = "draft");
+local.tony.createPost(title = "Fifth post", body = "Body 5", views = 2, averageRating = "3.6", status = "draft");
+</cfscript>