Usability Testing for Backend APIs with Postman and Supertest - SWDBD401 Backend Application Development

Usability testing for a backend API means verifying that the API behaves correctly and predictably from the consumer’s perspective. This includes testing that error messages are meaningful, input validation rejects bad data with clear feedback, and behaviors like pagination work as documented. This page covers Postman, Newman, Supertest with a real MySQL test database, and Joi validation.

What Is API Usability Testing

For a backend API, usability testing answers:

Do endpoints return correct HTTP status codes in all cases?
Are error messages informative and consistent?
Is request validation comprehensive and helpful?
Does pagination, filtering, and sorting work as expected?
Do all documented endpoints behave as documented?

API usability testing sits between unit testing (mocked DB) and full E2E testing. It tests complete HTTP request-response cycles against the running application with a real test database.

Integration Testing vs Unit Testing

Aspect	Unit Testing	Integration Testing
Database	Mocked (pool.execute is a jest.fn())	Real MySQL test database
Speed	Very fast (ms)	Slower (hundreds of ms)
Confidence	Tests logic	Tests full stack including SQL
Tools	Jest + jest.mock()	Supertest + real MySQL

Postman: Manual API Testing

Creating a Collection

Create collection

Click Collections in sidebar, then + to create “SWDBD401 API Tests”.

Add folders per resource

Create folders: Auth, Users, Posts. Organize requests inside.

Set environment variables

Create an environment: baseUrl = http://localhost:3000, token = (empty initially).

Write test scripts

Add test scripts in the Tests tab of each request.

Postman Test Scripts

// POST /auth/login — capture token for subsequent requests
pm.test("Login returns 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Response has token", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property('token');
  pm.environment.set('token', json.token); // Save for other requests
});

// GET /users — check array response
pm.test("Returns array of users", function () {
  const json = pm.response.json();
  pm.expect(json.data).to.be.an('array');
  pm.expect(json.pagination.total).to.be.a('number');
});

// POST /users without email — check 400
pm.test("Returns 400 on missing email", function () {
  pm.response.to.have.status(400);
  const json = pm.response.json();
  pm.expect(json.message).to.be.a('string');
});

Newman: CLI Runner

npm install -g newman

# Export collection from Postman: Collection > ... > Export v2.1

newman run collection.json
newman run collection.json --environment environment.json

# HTML report
npm install -g newman-reporter-htmlextra
newman run collection.json --reporters htmlextra --reporter-htmlextra-export report.html

MySQL Test Database Setup

Never run integration tests against your development or production database.

# Create a test database in MySQL
mysql -u root -p -e "CREATE DATABASE swdbd_test;"

# .env.test
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASS=yourpassword
DB_NAME=swdbd_test
NODE_ENV=test
JWT_SECRET=test-secret-key-at-least-32-characters-long
PORT=3001

{
  "scripts": {
    "test": "cross-env NODE_ENV=test jest --forceExit"
  },
  "jest": {
    "testEnvironment": "node",
    "setupFiles": ["dotenv/config"],
    "testTimeout": 30000
  }
}

Database Seeding and Teardown

// tests/helpers/db.js
const pool = require('../../config/db');

async function clearTables() {
  await pool.execute('SET FOREIGN_KEY_CHECKS = 0');
  await pool.execute('TRUNCATE TABLE audit_logs');
  await pool.execute('TRUNCATE TABLE users');
  await pool.execute('SET FOREIGN_KEY_CHECKS = 1');
}

async function seedUsers(users) {
  const bcrypt = require('bcrypt');
  for (const user of users) {
    const hashed = await bcrypt.hash(user.password, 10);
    await pool.execute(
      'INSERT INTO users (name, email, password, role) VALUES (?, ?, ?, ?)',
      [user.name, user.email, hashed, user.role || 'user']
    );
  }
}

module.exports = { clearTables, seedUsers };

Supertest Integration Tests

// tests/users.integration.test.js
const request = require('supertest');
const app = require('../app');
const pool = require('../config/db');
const jwt = require('jsonwebtoken');
const { clearTables, seedUsers } = require('./helpers/db');

let adminToken;

beforeAll(async () => {
  adminToken = jwt.sign({ sub: 1, role: 'admin' }, process.env.JWT_SECRET, { expiresIn: '1h' });
});

beforeEach(async () => {
  await clearTables();
  await seedUsers([
    { name: 'Alice', email: 'alice@test.com', password: 'password123', role: 'admin' },
    { name: 'Bob', email: 'bob@test.com', password: 'password123', role: 'user' }
  ]);
});

afterAll(async () => {
  await pool.end(); // Close all pool connections
});

describe('POST /api/v1/users', () => {
  it('creates a user and returns 201', async () => {
    const res = await request(app)
      .post('/api/v1/users')
      .send({ name: 'Carol', email: 'carol@test.com', password: 'password123' });

    expect(res.status).toBe(201);
    expect(res.body.data.email).toBe('carol@test.com');
    expect(res.body.data.password).toBeUndefined();
  });

  it('returns 400 with message when email is missing', async () => {
    const res = await request(app)
      .post('/api/v1/users')
      .send({ name: 'Dan', password: 'password123' });

    expect(res.status).toBe(400);
    expect(res.body.message).toBeTruthy();
  });

  it('returns 409 on duplicate email', async () => {
    const res = await request(app)
      .post('/api/v1/users')
      .send({ name: 'Alice2', email: 'alice@test.com', password: 'password123' });

    expect(res.status).toBe(409);
  });
});

describe('GET /api/v1/users (paginated)', () => {
  it('returns paginated users', async () => {
    const res = await request(app)
      .get('/api/v1/users?page=1&limit=1')
      .set('Authorization', `Bearer ${adminToken}`);

    expect(res.status).toBe(200);
    expect(res.body.data).toHaveLength(1);
    expect(res.body.pagination.total).toBe(2);
    expect(res.body.pagination.pages).toBe(2);
  });
});

Input Validation with Joi

npm install joi

// validation/userValidation.js
const Joi = require('joi');

const createUserSchema = Joi.object({
  name: Joi.string().trim().min(2).max(100).required().messages({
    'string.min': 'Name must be at least 2 characters',
    'any.required': 'Name is required'
  }),
  email: Joi.string().email().lowercase().required().messages({
    'string.email': 'Please provide a valid email',
    'any.required': 'Email is required'
  }),
  password: Joi.string().min(8).required().messages({
    'string.min': 'Password must be at least 8 characters',
    'any.required': 'Password is required'
  }),
  role: Joi.string().valid('user', 'admin').default('user')
});

module.exports = { createUserSchema };

// middleware/validate.js
function validate(schema) {
  return (req, res, next) => {
    const { error, value } = schema.validate(req.body, { abortEarly: false });
    if (error) {
      const errors = error.details.map(d => ({ field: d.path.join('.'), message: d.message }));
      return res.status(422).json({ message: 'Validation failed', errors });
    }
    req.body = value;
    next();
  };
}
module.exports = validate;

Testing Error Response Quality

describe('Error response quality', () => {
  it('validation error includes field names', async () => {
    const res = await request(app)
      .post('/api/v1/users')
      .send({ name: 'x' });

    expect(res.status).toBe(422);
    expect(res.body.errors).toBeInstanceOf(Array);
    expect(res.body.errors[0]).toHaveProperty('field');
    expect(res.body.errors[0]).toHaveProperty('message');
  });

  it('returns 401 on protected route without token', async () => {
    const res = await request(app).get('/api/v1/users');
    expect(res.status).toBe(401);
    expect(res.body.message).toBeTruthy();
  });
});

Key Terms

Term	Definition
Integration test	Test that verifies multiple components (controller + MySQL) work together
API contract	Documented agreement about endpoint behavior: inputs, outputs, status codes
Postman collection	Saved set of API requests organized in folders
Newman	CLI tool to run Postman collections in CI/CD pipelines
Joi	Schema validation library for JavaScript objects
Test database	Separate MySQL database used only during tests
422 Unprocessable Entity	Status for syntactically valid requests that fail business validation rules

Common Mistakes

Running integration tests against the development database

Tests truncate tables. Always use a separate DB_NAME_TEST database via .env.test and cross-env NODE_ENV=test.

Not closing the MySQL pool after tests

If pool.end() is not called in afterAll, Jest hangs after tests complete because the pool keeps Node.js alive.

Only testing happy paths

Usability testing must cover error paths: missing fields, duplicate emails, unauthorized access, not found IDs. Users always hit these paths.

Returning 500 for validation failures

Client input mistakes should return 400 or 422, not 500. A 500 hides the real cause and forces clients to guess what went wrong.

​What Is API Usability Testing

​Integration Testing vs Unit Testing

​Postman: Manual API Testing

​Creating a Collection

​Postman Test Scripts

​Newman: CLI Runner

​MySQL Test Database Setup

​Database Seeding and Teardown

​Supertest Integration Tests

​Input Validation with Joi

​Testing Error Response Quality

​Key Terms

​Common Mistakes

What Is API Usability Testing

Integration Testing vs Unit Testing

Postman: Manual API Testing

Creating a Collection

Postman Test Scripts

Newman: CLI Runner

MySQL Test Database Setup

Database Seeding and Teardown

Supertest Integration Tests

Input Validation with Joi

Testing Error Response Quality

Key Terms

Common Mistakes