Testing & Assertions

Testing & Assertions

ApiArk provides two ways to test API responses: declarative YAML assertions (simple, no code) and JavaScript test blocks (powerful, Chai.js-based).

---

Declarative Assertions (YAML)

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 }

Available Operators

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 } }

Accessing Nested Values

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 }

---

JavaScript Tests

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");
  });

Chai.js Assertion Styles

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" });

---

Test Results Panel

After running a request with tests:

1. Click the Tests tab in the response panel
2. See each test with pass/fail status
3. Failed tests show the assertion error message
4. Total pass/fail count in the tab badge

---

JSON Schema Validation

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);
});

---

Combining Assertions and Tests

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);
  });