{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreid3ztxnpg4suvrn43uii6d2k3ie27o3jjws2nhdgcezlbiuu7slxy",
    "uri": "at://did:plc:25rdn5elo5izoxrmtis34zuk/app.bsky.feed.post/3mp73oxdg2yu2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreihdafjo3x7ur6zqub6f76tqzlfr2t37datzkpuuhj5d6fvkhdp2vu"
    },
    "mimeType": "image/webp",
    "size": 574492
  },
  "path": "/sushant_joshi_79_/the-only-3-types-of-assertions-you-need-for-rest-api-tests-16ek",
  "publishedAt": "2026-06-26T13:36:29.000Z",
  "site": "https://dev.to",
  "tags": [
    "ai",
    "api",
    "startup",
    "testing",
    "https://totalshiftleft.ai/blog/rest-api-testing-best-practices"
  ],
  "textContent": "I went through 2,400 of our team's API test assertions last month. 91% of them fall into three categories.*\n\nThat number surprised me.\n\nNot because it was low.\n\nBecause it was so high.\n\nI expected to find dozens of assertion patterns:\n\n  * Header assertions\n  * Pagination assertions\n  * Security assertions\n  * Performance assertions\n  * Database validations\n  * Custom business rules\n\n\n\nInstead, almost everything we had written could be grouped into just three buckets.\n\nWhen I removed duplicate patterns and categorized the assertions, 91% of them fit into:\n\n  1. **Schema Assertions**\n  2. **Identity Assertions**\n  3. **Side-Effect Assertions**\n\n\n\nThe remaining 9%?\n\nMost of them probably shouldn't exist.\n\nIf you're building or maintaining REST API tests, understanding these three categories will dramatically simplify how you think about testing.\n\n#  Why Most API Test Suites Become Hard to Maintain\n\nA lot of test suites grow organically.\n\nA developer writes:\n\n\n\n    expect(response.status).toBe(200);\n\n\nAnother adds:\n\n\n\n    expect(response.body.name).toBe('John');\n\n\nSomeone else adds:\n\n\n\n    expect(response.body.items.length).toBe(3);\n\n\nEventually the suite contains thousands of assertions.\n\nMany of them:\n\n  * Duplicate each other\n  * Validate implementation details\n  * Add maintenance without adding confidence\n\n\n\nThe goal isn't to write more assertions.\n\nThe goal is to write the assertions that actually matter.\n\n#  1. Schema Assertions (The One Most Tests Skip)\n\nThis is the most undervalued type of API assertion.\n\nA schema assertion answers:\n\n> Does the response still match the contract?\n\nSuppose your endpoint returns:\n\n\n\n    {\n      \"id\": 123,\n      \"name\": \"John Smith\",\n      \"email\": \"john@example.com\"\n    }\n\n\nTomorrow someone changes it to:\n\n\n\n    {\n      \"id\": \"123\",\n      \"fullName\": \"John Smith\"\n    }\n\n\nThe endpoint still returns:\n\n\n\n    200 OK\n\n\nBut consumers may immediately break.\n\nThis is why schema assertions matter.\n\n##  What Schema Assertions Validate\n\n  * Required fields exist\n  * Data types are correct\n  * Fields have not disappeared\n  * Arrays contain the right structure\n  * Response contracts remain compatible\n\n\n\n##  Example JSON Schema Assertion\n\n\n    expect(response.body).toMatchSchema({\n      type: 'object',\n      required: ['id', 'name'],\n      properties: {\n        id: {\n          type: 'integer'\n        },\n        name: {\n          type: 'string'\n        }\n      }\n    });\n\n\n##  Why Teams Skip This\n\nBecause checking:\n\n\n\n    expect(response.status)\n      .toBe(200);\n\n\nfeels sufficient.\n\nIt isn't.\n\nThe biggest API regressions I see are contract changes that still return successful responses.\n\nThis is why **json schema assertion** techniques provide so much value.\n\n#  Copy-Paste Template: Schema Assertion\n\n\n    expect(response.body)\n      .toMatchSchema(schema);\n\n\nOr:\n\n\n\n    expect(response.body.id)\n      .toEqual(expect.any(Number));\n\n\n#  2. Identity Assertions (The Value You Actually Care About)\n\nThis is the category most people think of when they hear \"API testing.\"\n\nAn identity assertion answers:\n\n> Did the API return the correct business value?\n\nExample:\n\n\n\n    {\n      \"discount\": 20\n    }\n\n\nThe contract may be valid.\n\nThe endpoint may return `200`.\n\nBut if the expected discount is:\n\n\n\n    {\n      \"discount\": 50\n    }\n\n\nthe API is still broken.\n\n##  Identity Assertions Validate\n\n  * Business calculations\n  * Field values\n  * Sorting\n  * Filtering\n  * Authorization decisions\n  * Domain rules\n\n\n\n##  Example\n\n\n    expect(response.body.discount)\n      .toBe(20);\n\n\nOr:\n\n\n\n    expect(response.body.status)\n      .toBe('ACTIVE');\n\n\n##  Why Identity Assertions Matter\n\nCustomers care about values.\n\nThey do not care that:\n\n\n\n    {\n      \"discount\": {\n        \"type\": \"integer\"\n      }\n    }\n\n\nis valid.\n\nThey care that the discount is correct.\n\n#  Copy-Paste Template: Identity Assertion\n\n\n    expect(response.body.field)\n      .toBe(expectedValue);\n\n\nOr:\n\n\n\n    expect(response.body)\n      .toEqual(expectedObject);\n\n\n#  3. Side-Effect Assertions (The Ones That Prove the Work Happened)\n\nThis category gets overlooked surprisingly often.\n\nAn API can return:\n\n\n\n    200 OK\n\n\nand still fail completely.\n\nConsider:\n\n\n\n    POST /orders\n\n\nThe endpoint returns success.\n\nBut:\n\n  * The database row wasn't created.\n  * The message wasn't published.\n  * The email wasn't sent.\n\n\n\nThe business process failed.\n\n##  Side-Effect Assertions Validate\n\n  * Database writes\n  * Queue messages\n  * Event publication\n  * Emails\n  * Audit logs\n  * Third-party integrations\n\n\n\n##  Example Database Assertion\n\n\n    expect(orderRepository.find(orderId))\n      .not.toBeNull();\n\n\n##  Example Queue Assertion\n\n\n    expect(queue.contains(orderCreatedEvent))\n      .toBe(true);\n\n\n##  Why Side Effects Matter\n\nMany APIs exist solely to trigger something else.\n\nThe response itself is often the least important part.\n\nFor example:\n\n\n\n    POST /payments\n\n\nNobody cares about:\n\n\n\n    {\n      \"success\": true\n    }\n\n\nWhat matters is:\n\n  * Was the payment captured?\n  * Was the invoice generated?\n  * Was the receipt sent?\n\n\n\n#  Copy-Paste Template: Side-Effect Assertion\n\n\n    expect(databaseRecord)\n      .toExist();\n\n\nOr:\n\n\n\n    expect(publishedEvent)\n      .toBeDefined();\n\n\n#  The 9% That Didn't Fit\n\nAfter categorizing our assertions, around 9% remained.\n\nExamples included:\n\n\n\n    expect(response.body.items.length)\n      .toBe(5);\n\n\n\n    expect(response.body.createdAt)\n      .toBe('2026-07-01');\n\n\n\n    expect(response.body.version)\n      .toBe('1.2.8');\n\n\nMany of these were:\n\n  * Brittle\n  * Overly specific\n  * Tied to implementation details\n\n\n\n#  Why Most of Them Should Be Deleted\n\nAsk yourself:\n\n> If this assertion failed tomorrow, would users actually notice?\n\nIf the answer is:\n\n> Probably not.\n\nDelete it.\n\nA surprising amount of maintenance comes from assertions that don't provide meaningful confidence.\n\n#  Bad Assertions\n\n\n    expect(responseTime)\n      .toBe(183);\n\n\n\n    expect(itemCount)\n      .toBe(17);\n\n\n\n    expect(timestamp)\n      .toEqual('2026-07-28T08:00:00Z');\n\n\nThese tend to break constantly.\n\n#  Better Assertions\n\n\n    expect(responseTime)\n      .toBeLessThan(500);\n\n\n\n    expect(itemCount)\n      .toBeGreaterThan(0);\n\n\n\n    expect(timestamp)\n      .toBeDefined();\n\n\nThese are more resilient.\n\n#  The Assertion Pyramid I Recommend\n\nWhenever I write a new API test, I ask three questions.\n\n##  First\n\nDoes the response still match the contract?\n\n→ Schema Assertion.\n\n##  Second\n\nDid the API return the correct business value?\n\n→ Identity Assertion.\n\n##  Third\n\nDid the system actually perform the work?\n\n→ Side-Effect Assertion.\n\nMost useful tests contain at least one of these categories.\n\nMany contain all three.\n\nExample:\n\n\n\n    expect(response.body)\n      .toMatchSchema(userSchema);\n\n    expect(response.body.name)\n      .toBe('John');\n\n    expect(databaseUser)\n      .toExist();\n\n\nThree assertions.\n\nThree different guarantees.\n\nHigh confidence.\n\nLow maintenance.\n\n#  Final Thoughts\n\nWhen we reduced our thousands of assertions down to categories, we realized something important:\n\nMost API testing is simpler than we make it.\n\nThe majority of valuable assertions answer only three questions:\n\n  1. Is the contract still valid?\n  2. Is the business value correct?\n  3. Did the side effect happen?\n\n\n\nEverything else should justify its existence.\n\nIf an assertion doesn't increase confidence or protect against meaningful regressions, it may not belong in the suite.\n\nThat's why I now start every API test by deciding which of these three categories I'm actually trying to validate.\n\nIf you'd like to go deeper into building maintainable API suites, I highly recommend **the REST API testing best practices guide** :\n\nhttps://totalshiftleft.ai/blog/rest-api-testing-best-practices\n\nBecause the best API tests aren't the ones with the most assertions.\n\nThey're the ones with the right assertions.",
  "title": "The Only 3 Types of Assertions You Need for REST API Tests"
}