Runbook 09 — Cypress API harness (setup + first 3 tests)

Scope

• Add an API-first Cypress harness (no UI dependency in Sprint 09).
• Enforce env-driven base URL (no hardcoded domains in tests).
• Ship 3 starter API tests: GET + POST + Negative.
• Prove deterministic data strategy (unique data per POST).

Exit criteria

• ✔ Cypress installed and runnable headless (npx cypress run).
• ✔ API_BASE_URL is required; missing env fails fast.
• ✔ 3 API tests pass locally (GET + POST + Negative).
• ✔ POST uses unique data per test run (parallel-safe pattern).
• ✔ Assertions validate payload structure, not just status codes.

Env contract

Setup

Install

npm install --save-dev cypress

Initialize Cypress folder structure

npx cypress open

Config (env-driven base URL)

Starter tests

File: cypress/e2e/api/articles.cy.js

npm install --save-dev cypress

npx cypress open

// cypress.config.js
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: process.env.API_BASE_URL,
    setupNodeEvents(on, config) {
      if (!config.baseUrl) {
        throw new Error('Missing required env: API_BASE_URL')
      }
      return config
    },
  },
})

describe('API.ARTICLES.001 - Get Articles', () => {
  it('returns list with expected shape', () => {
    cy.request('GET', '/api/articles').then((res) => {
      expect(res.status).to.eq(200)
      expect(res.body).to.have.property('articles')
      expect(res.body.articles).to.be.an('array')

      if (res.body.articles.length > 0) {
        const a = res.body.articles[0]
        expect(a).to.have.property('title')
        expect(a).to.have.property('slug')
        expect(a).to.have.property('author')
      }
    })
  })
})

describe('API.ARTICLES.002 - Create Article', () => {
  it('creates a unique article (requires auth)', () => {
    const title = `Sprint09 ${Date.now()}`
    const token = Cypress.env('API_TOKEN')

    // If your API requires login, set API_TOKEN via env or add a login helper in Sprint 10.
    expect(token, 'API_TOKEN is required for create').to.be.a('string').and.not.be.empty

    cy.request({
      method: 'POST',
      url: '/api/articles',
      headers: { Authorization: `Token ${token}` },
      body: {
        article: {
          title,
          description: 'Cypress API harness seed',
          body: 'Sprint 09 POST test'
        }
      }
    }).then((res) => {
      expect(res.status).to.eq(201)
      expect(res.body).to.have.property('article')
      expect(res.body.article.title).to.eq(title)
      expect(res.body.article).to.have.property('slug')
    })
  })
})

describe('API.ARTICLES.003 - Unauthorized Create', () => {
  it('fails with 401 when no token provided', () => {
    cy.request({
      method: 'POST',
      url: '/api/articles',
      failOnStatusCode: false,
      body: {
        article: {
          title: `ShouldFail ${Date.now()}`,
          description: 'no auth',
          body: 'negative path'
        }
      }
    }).then((res) => {
      expect(res.status).to.eq(401)
    })
  })
})

export API_BASE_URL="http://sut.testlab:3001"
curl -sS "$API_BASE_URL/api/articles" | head

export API_BASE_URL="http://sut.testlab:3001"
export API_TOKEN="<token>"   # store in shell/CI secrets, never commit
npx cypress run

Commands

Preflight: verify API reachable

export API_BASE_URL="http://sut.testlab:3001"
curl -sS "$API_BASE_URL/api/articles" | head

Run Cypress headless

export API_BASE_URL="http://sut.testlab:3001"
export API_TOKEN="<token>"   # store in shell/CI secrets, never commit
npx cypress run

Expected outputs

• ✔ Cypress launches and executes the 3 specs.
• ✔ Missing API_BASE_URL fails immediately with a clear error.
• ✔ GET test validates response structure.
• ✔ POST test creates a unique article and asserts returned fields.
• ✔ Negative test returns 401 when no token provided.

Failure modes

• Wrong baseUrl shape: baseUrl includes /api but tests also call /api/... → double /api/api. Pick one convention.
• Auth missing: POST create requires token → provide API_TOKEN or implement login helper (Sprint 10).
• State collision: non-unique titles/slugs cause conflicts under parallel runs → ensure unique IDs via timestamp/GUID.
• CI mismatch: works locally but not in CI → confirm runner can resolve sut.testlab (name/IP contract).
• Over-asserting dynamic fields: avoid asserting full objects with fields that vary (timestamps, counts).