The open-source agent harness - the runtime layer that turns an LLM into a working agent.
import { queryBuilder } from "../../../src/core/url/QueryStringBuilder";
describe("QueryStringBuilder", () => {
describe("add() — default repeat format", () => {
it("adds a scalar string value", () => {
const qs = queryBuilder().add("key", "value").build();
expect(qs).toBe("key=value");
});
it("adds a scalar number value", () => {
const qs = queryBuilder().add("limit", 10).build();
expect(qs).toBe("limit=10");
});
it("adds a boolean value", () => {
const qs = queryBuilder().add("active", true).build();
expect(qs).toBe("active=true");
});
it("skips undefined values", () => {
const qs = queryBuilder().add("key", undefined).build();
expect(qs).toBe("");
});
it("skips null values", () => {
const qs = queryBuilder().add("key", null).build();
expect(qs).toBe("");
});
it("repeats array elements as separate key=value pairs", () => {
const qs = queryBuilder().add("color", ["red", "blue", "green"]).build();
expect(qs).toBe("color=red&color=blue&color=green");
});
it("skips undefined items within arrays", () => {
const qs = queryBuilder().add("color", ["red", undefined, "blue"]).build();
expect(qs).toBe("color=red&color=blue");
});
it("returns empty string for empty array", () => {
const qs = queryBuilder().add("color", []).build();
expect(qs).toBe("");
});
it("encodes special characters in keys and values", () => {
const qs = queryBuilder().add("my key", "hello world").build();
expect(qs).toBe("my%20key=hello%20world");
});
it("handles nested objects", () => {
const qs = queryBuilder().add("filter", { status: "active" }).build();
expect(qs).toBe("filter%5Bstatus%5D=active");
});
});
describe("add() — comma style", () => {
it("joins array values with literal commas", () => {
const qs = queryBuilder().add("tags", ["a", "b", "c"], { style: "comma" }).build();
expect(qs).toBe("tags=a,b,c");
});
it("handles single-element array", () => {
const qs = queryBuilder().add("tags", ["only"], { style: "comma" }).build();
expect(qs).toBe("tags=only");
});
it("returns empty string for empty array", () => {
const qs = queryBuilder().add("tags", [], { style: "comma" }).build();
expect(qs).toBe("");
});
it("skips undefined values", () => {
const qs = queryBuilder().add("tags", undefined, { style: "comma" }).build();
expect(qs).toBe("");
});
it("skips null values", () => {
const qs = queryBuilder().add("tags", null, { style: "comma" }).build();
expect(qs).toBe("");
});
it("treats scalar values same as default add()", () => {
const qs = queryBuilder().add("tag", "single", { style: "comma" }).build();
expect(qs).toBe("tag=single");
});
it("encodes commas within individual values as %2C", () => {
const qs = queryBuilder().add("items", ["a,b", "c"], { style: "comma" }).build();
expect(qs).toBe("items=a%2Cb,c");
});
it("encodes special characters in values", () => {
const qs = queryBuilder().add("tags", ["hello world", "foo&bar"], { style: "comma" }).build();
expect(qs).toBe("tags=hello%20world,foo%26bar");
});
});
describe("chaining", () => {
it("chains multiple add() calls", () => {
const qs = queryBuilder().add("limit", 10).add("offset", 20).build();
expect(qs).toBe("limit=10&offset=20");
});
it("chains add() with default and comma styles", () => {
const qs = queryBuilder()
.add("limit", 10)
.add("tags", ["ACCESS_GRANTED", "COPY", "DELETE"], { style: "comma" })
.add("active", true)
.build();
expect(qs).toBe("limit=10&tags=ACCESS_GRANTED,COPY,DELETE&active=true");
});
it("skips undefined/null params in chain without breaking", () => {
const qs = queryBuilder()
.add("a", "1")
.add("b", undefined)
.add("c", null, { style: "comma" })
.add("d", "4")
.build();
expect(qs).toBe("a=1&d=4");
});
});
describe("addMany()", () => {
it("adds all params from a record", () => {
const qs = queryBuilder().addMany({ limit: 10, offset: 20, name: "test" }).build();
expect(qs).toBe("limit=10&offset=20&name=test");
});
it("skips null and undefined values", () => {
const qs = queryBuilder().addMany({ a: "1", b: null, c: undefined, d: "4" }).build();
expect(qs).toBe("a=1&d=4");
});
it("handles empty record", () => {
const qs = queryBuilder().addMany({}).build();
expect(qs).toBe("");
});
it("works with comma-style override after addMany", () => {
const params = { limit: 10, tags: ["a", "b"], active: true };
const qs = queryBuilder().addMany(params).add("tags", params.tags, { style: "comma" }).build();
expect(qs).toBe("limit=10&tags=a,b&active=true");
});
it("handles array values with default repeat format", () => {
const qs = queryBuilder()
.addMany({ ids: [1, 2, 3] })
.build();
expect(qs).toBe("ids=1&ids=2&ids=3");
});
});
describe("mergeAdditional()", () => {
it("appends additional params", () => {
const qs = queryBuilder().add("limit", 10).mergeAdditional({ extra: "value" }).build();
expect(qs).toBe("limit=10&extra=value");
});
it("overrides existing keys (last-write-wins)", () => {
const qs = queryBuilder().add("limit", 10).mergeAdditional({ limit: 20 }).build();
expect(qs).toBe("limit=20");
});
it("handles undefined additional params", () => {
const qs = queryBuilder().add("limit", 10).mergeAdditional(undefined).build();
expect(qs).toBe("limit=10");
});
it("skips undefined values in additional params", () => {
const qs = queryBuilder().add("limit", 10).mergeAdditional({ extra: undefined }).build();
expect(qs).toBe("limit=10");
});
it("skips null values in additional params", () => {
const qs = queryBuilder().add("limit", 10).mergeAdditional({ extra: null }).build();
expect(qs).toBe("limit=10");
});
it("handles array values in additional params using repeat format", () => {
const qs = queryBuilder()
.mergeAdditional({ ids: [1, 2, 3] })
.build();
expect(qs).toBe("ids=1&ids=2&ids=3");
});
it("overrides a comma-style param with repeat format", () => {
const qs = queryBuilder()
.add("tags", ["a", "b"], { style: "comma" })
.mergeAdditional({ tags: ["x", "y"] })
.build();
expect(qs).toBe("tags=x&tags=y");
});
});
describe("build()", () => {
it("returns empty string when no params added", () => {
const qs = queryBuilder().build();
expect(qs).toBe("");
});
it("does not include leading ?", () => {
const qs = queryBuilder().add("key", "value").build();
expect(qs).not.toContain("?");
});
});
describe("end-to-end scenarios", () => {
it("matches expected query-parameters-openapi output pattern", () => {
const params: Record<string, unknown> = {
limit: 1,
id: "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
date: "2023-01-15",
deadline: "2024-01-15T09:30:00.000Z",
bytes: "SGVsbG8gd29ybGQh",
user: "user",
userList: ["user"],
optionalString: "optionalString",
nestedUser: "nestedUser",
excludeUser: "excludeUser",
filter: "filter",
tags: ["tags"],
optionalTags: undefined,
};
const qs = queryBuilder()
.addMany(params)
.add("tags", params.tags, { style: "comma" })
.add("optionalTags", params.optionalTags, { style: "comma" })
.mergeAdditional(undefined)
.build();
expect(qs).toContain("limit=1");
expect(qs).toContain("tags=tags");
expect(qs).not.toContain("optionalTags");
});
});
});