-
Notifications
You must be signed in to change notification settings - Fork 57
Testing & Assertions
Anes Berbic edited this page Mar 13, 2026
·
1 revision
ApiArk provides two ways to test API responses: declarative YAML assertions (simple, no code) and JavaScript test blocks (powerful, Chai.js-based).
Add an assert block to any request YAML file. No scripting required.
assert: status: 200 body.users.length: { gt: 0 } body.users[0].email: { matches: "^.+@.+$" } headers.content-type: { contains: "application/json" } responseTime: { lt: 2000 }
| Operator | Description | Example |
|---|---|---|
eq |
Equals (default if bare value) |
status: 200 or status: { eq: 200 }
|
neq |
Not equals | status: { neq: 500 } |
gt |
Greater than | body.count: { gt: 0 } |
gte |
Greater than or equal | body.count: { gte: 1 } |
lt |
Less than | responseTime: { lt: 2000 } |
lte |
Less than or equal | responseTime: { lte: 5000 } |
in |
Value in array | status: { in: [200, 201] } |
notIn |
Value not in array | status: { notIn: [500, 502, 503] } |
contains |
String/array contains | body.name: { contains: "John" } |
notContains |
Does not contain | body.error: { notContains: "fatal" } |
matches |
Regex match | body.email: { matches: "^.+@.+\\..+$" } |
type |
JavaScript type check | body.id: { type: string } |
exists |
Property exists | body.token: { exists: true } |
length |
Array/string length | body.users: { length: 10 } |
schema |
JSON Schema validation | body: { schema: { type: object } } |
Use dot notation and array indices:
assert: body.data.users[0].name: { type: string } body.data.pagination.total: { gt: 0 } body.meta.version: "2.0" headers.x-rate-limit-remaining: { gt: 0 }
For more complex validation, use tests blocks with full JavaScript:
tests: | ark.test("should return paginated users", () => { const body = ark.response.json(); // Status check ark.expect(ark.response.status).to.equal(200); // Structure check ark.expect(body).to.have.property("users"); ark.expect(body).to.have.property("pagination"); // Data validation ark.expect(body.users).to.be.an("array"); ark.expect(body.users.length).to.be.at.most(20); // Each user has required fields body.users.forEach(user => { ark.expect(user).to.have.all.keys("id", "name", "email"); ark.expect(user.email).to.match(/^.+@.+\..+$/); }); }); ark.test("pagination metadata is correct", () => { const { pagination } = ark.response.json(); ark.expect(pagination.page).to.be.a("number"); ark.expect(pagination.perPage).to.equal(20); ark.expect(pagination.total).to.be.at.least(0); }); ark.test("response time is acceptable", () => { ark.expect(ark.response.time).to.be.below(2000); }); ark.test("content type is JSON", () => { const ct = ark.response.headers["content-type"]; ark.expect(ct).to.include("application/json"); });
ApiArk supports the full Chai.js expect API:
// Equality ark.expect(value).to.equal(expected); ark.expect(value).to.deep.equal({ key: "value" }); ark.expect(value).to.not.equal(unexpected); // Type checking ark.expect(value).to.be.a("string"); ark.expect(value).to.be.an("array"); ark.expect(value).to.be.null; ark.expect(value).to.be.undefined; ark.expect(value).to.be.true; // Comparison ark.expect(number).to.be.above(5); ark.expect(number).to.be.below(100); ark.expect(number).to.be.at.least(1); ark.expect(number).to.be.at.most(50); ark.expect(number).to.be.within(1, 100); // String ark.expect(str).to.include("substring"); ark.expect(str).to.match(/pattern/); ark.expect(str).to.have.lengthOf(10); // Array ark.expect(arr).to.include("item"); ark.expect(arr).to.have.lengthOf(5); ark.expect(arr).to.be.empty; ark.expect(arr).to.have.members(["a", "b", "c"]); // Object ark.expect(obj).to.have.property("key"); ark.expect(obj).to.have.property("key", "value"); ark.expect(obj).to.have.all.keys("id", "name", "email"); ark.expect(obj).to.have.any.keys("id", "uuid"); ark.expect(obj).to.deep.include({ name: "John" });
After running a request with tests:
- Click the Tests tab in the response panel
- See each test with pass/fail status
- Failed tests show the assertion error message
- Total pass/fail count in the tab badge
Validate response structure against a JSON Schema:
assert: body: schema: type: object required: - id - name - email properties: id: type: string pattern: "^usr_[a-z0-9]+$" name: type: string minLength: 1 email: type: string format: email age: type: integer minimum: 0 maximum: 150
Or in JavaScript using Ajv:
ark.test("response matches schema", () => { const schema = { type: "object", required: ["id", "name"], properties: { id: { type: "string" }, name: { type: "string" } } }; const body = ark.response.json(); ark.expect(body).to.matchSchema(schema); });
You can use both in the same request. Declarative assertions run first, then JavaScript tests:
# Quick checks (no code needed) assert: status: 200 responseTime: { lt: 3000 } body.success: true # Detailed validation (with code) tests: | ark.test("business logic validation", () => { const body = ark.response.json(); const total = body.items.reduce((sum, item) => sum + item.price, 0); ark.expect(total).to.equal(body.totalPrice); });
Getting Started
Core Features
Advanced Features
Tools
Resources