◈ API REST Tester

A lightweight, zero-dependency API testing framework built in pure Node.js. Tests real public APIs, validates responses with custom assertions, and generates a beautiful HTML report — all without any external test libraries.

Built by Jhon Carlos Acevedo Mendoza — QA Analyst with hands-on experience testing SaaS platforms and international health applications.

---

✨ What Makes This Different

• No dependencies — zero npm install needed. Uses native fetch (Node 18+)
• Custom assertion engine — built from scratch, similar to Jest's expect()
• HTML Report — self-contained, professional report generated after every run
• JSON Report — machine-readable output for CI/CD pipelines
• Multi-API coverage — 3 real public APIs tested across 5 suites

---

📁 Project Structure

api-rest-tester/
├── runner.js                    # Core engine: assertion engine, request helper, suite runner
├── tests/
│   ├── index.js                 # Suite registry (import all suites here)
│   ├── jsonplaceholder.test.js  # Posts, Users, Comments suites
│   ├── pokeapi.test.js          # PokéAPI suite
│   └── weather.test.js          # Open-Meteo weather suite
├── utils/
│   ├── logger.js                # Colored terminal output
│   └── reporter.js              # HTML report generator
├── reports/                     # Auto-generated reports (gitignored except latest)
└── README.md

---

🧪 APIs Under Test

API	URL	Tests
JSONPlaceholder	jsonplaceholder.typicode.com	Posts CRUD, Users, Comments
PokéAPI	pokeapi.co/api/v2	Pokemon, Types, Abilities, Pagination
Open-Meteo	api.open-meteo.com/v1	Current weather, Forecast, Error handling

---

📊 Total Test Coverage

Suite	Tests	What's Validated
Posts	8	GET, POST, PUT, PATCH, DELETE, Filter, 404, Schema
Users	4	Schema, Email format, Address, Nested endpoint
Comments	3	Count, Filter, Nested, Schema
PokéAPI	6	Schema, ID lookup, 404, Pagination, Type, Ability
Weather	4	Current, Coords, Hourly array, 400 error
Total	25

---

⚡ Getting Started

Prerequisites

• Node.js v18 or higher (for native fetch)

node --version   # should be >= 18.0.0

Run Tests

# Clone
git clone https://github.com/your-username/api-rest-tester.git
cd api-rest-tester

# Run all suites
node runner.js

# Run specific suite
node runner.js --suite posts
node runner.js --suite poke
node runner.js --suite weather

No npm install needed. No dependencies. Just Node.js.

---

📄 Reports

After every run, two reports are generated in reports/:

File	Format	Use
report-TIMESTAMP.html	HTML	Open in browser for visual report
results-TIMESTAMP.json	JSON	CI/CD, parsing, integration
latest-report.html	HTML	Always points to the most recent run

Open the HTML report:

# macOS
open reports/latest-report.html

# Linux
xdg-open reports/latest-report.html

# Windows
start reports/latest-report.html

---

✅ Assertion Engine

Built-in assertions available via expect(value):

expect(res.status).toBe(200)
expect(res.body).toBeArray()
expect(res.body).toHaveLength(100)
expect(res.body).toMatchSchema(['id', 'name', 'email'])
expect(res.body.email).toBeValidEmail()
expect(res.responseTime).toBeLessThan(3000)
expect(value).toBeGreaterThan(0)
expect(value).toContain('string')
expect(value).toBeTruthy()
expect(value).toBeTypeOf('string')

---

➕ Adding a New Test Suite

// tests/my-api.test.js
import { request, expect, assert } from '../runner.js';

export const myApiSuite = {
  name:    'My API — Users',
  baseURL: 'https://my-api.com',
  tests: [
    {
      name: 'GET /users — returns list',
      fn: async (ctx) => {
        const res = await request('https://my-api.com/users');
        assert(expect(res.status).toBe(200), 'Status 200', ctx);
        assert(expect(res.body).toBeArray(), 'Returns array', ctx);
      }
    }
  ]
};

Then register it in tests/index.js:

import { myApiSuite } from './my-api.test.js';
export const testSuites = [...existingSuites, myApiSuite];

---

🔧 CI/CD Integration

The runner exits with code 1 if any tests fail, making it compatible with any CI pipeline:

# GitHub Actions example
- name: Run API Tests
  run: node runner.js

# The step fails automatically if tests fail

---

🧠 Concepts Demonstrated

• ✅ REST API testing (GET, POST, PUT, PATCH, DELETE)
• ✅ Custom assertion engine built from scratch
• ✅ Schema validation (key presence checking)
• ✅ Email format validation with regex
• ✅ Response time assertions
• ✅ HTTP status code validation
• ✅ Filter / query param testing
• ✅ Error handling (404, 400, timeout)
• ✅ Nested endpoint testing
• ✅ HTML report generation
• ✅ JSON report for CI/CD
• ✅ ES Modules (import/export)
• ✅ Colored terminal output

---

📄 License

MIT © Jhon Carlos Acevedo Mendoza