This project is a boilerplate Node.js RESTful API server built with the Express.js framework supporting CRUD operations (Create, Read, Update, Delete) for a simple Item entity, featuring/showcasing:
- Swagger UI documentation for easy API reference and exploration.
- Jest and supertest unit tests to verify all API endpoints accurately.
- End-to-End tests using Cypress that verify both the availability of Swagger docs and the functionality of every CRUD endpoint.
- Features
- Getting Started
- Running the Application
- API Endpoints
- Swagger API Documentation
- Test Coverage
- CI/CD with GitHub Actions
- Folder Structure
- Customization
- TODO
- Express API with full CRUD for items
- Swagger UI at
/api-docs/ http://localhost:3333/api-docs for live documentation - In-memory data storage (easy to swap with any database)
- Cypress End-to-End tests:
- Validate availability and accuracy of Swagger docs
- Automated checks for all CRUD endpoint operations
⇡ Return to the Table of Contents
- Node.js (v14+ recommended)
- npm
- Clone the repo:
git clone <this-repo> - Change to the project folder:
cd <project-folder> - Install dependencies:
npm install
⇡ Return to the Table of Contents
node app.js- API is accessible at: http://localhost:3333
- Swagger API docs accessible at: http://localhost:3333/api-docs
⇡ Return to the Table of Contents
| Method | Endpoint | Description |
|---|---|---|
| GET | /items |
List all items |
| GET | /items/:id |
Get item by ID |
| POST | /items |
Create a new item |
| PUT | /items/:id |
Update an item by ID |
| DELETE | /items/:id |
Delete an item by ID |
- See complete request/response schemas at /api-docs.
⇡ Return to the Table of Contents
- Swagger UI auto-generates API docs based on code comments and Swagger OpenAPI definitions.
- Interactive API explorer found at /api-docs.
⇡ Return to the Table of Contents
Unit tests are implemented in Jest and supertest inside the tests/ directory to verify all API endpoints accurately.
- Tests each
/itemsCRUD endpoint for correctness and error handling - Runs in-memory (no DB required)
Run tests manually:
npm test- Expected output sample:
(main) % npm test
> [email protected] test
> jest
console.log
Server running on http://localhost:3333
at Server.log (app.js:191:13)
console.log
Swagger docs available at http://localhost:3333/api-docs
at Server.log (app.js:192:13)
PASS tests/app.test.js
API Unit Tests
✓ should create an item (31 ms)
✓ should list items (3 ms)
✓ should get item by id (2 ms)
✓ should update item (2 ms)
✓ should delete item (4 ms)
✓ should return 404 for missing item (1 ms)
Test Suites: 1 passed, 1 total
Tests: 6 passed, 6 total
Snapshots: 0 total
Time: 0.31 s, estimated 1 s
Ran all test suites.
Run unit tests automatically on server startup:
RUN_TESTS=true node server.js- Expected output sample:
(main) % RUN_TESTS=true node server.js
Server running on http://localhost:3333
Swagger docs available at http://localhost:3333/api-docs
Server running on http://localhost:3333
Swagger docs available at http://localhost:3333/api-docs
Running unit tests...
> [email protected] test
> jest
console.log
Server running on http://localhost:3333
at Server.log (app.js:191:13)
console.log
Swagger docs available at http://localhost:3333/api-docs
at Server.log (app.js:192:13)
PASS tests/app.test.js
API Unit Tests
✓ should create an item (29 ms)
✓ should list items (3 ms)
✓ should get item by id (2 ms)
✓ should update item (2 ms)
✓ should delete item (2 ms)
✓ should return 404 for missing item (1 ms)
Test Suites: 1 passed, 1 total
Tests: 6 passed, 6 total
Snapshots: 0 total
Time: 0.265 s, estimated 1 s
Ran all test suites.
⇡ Return to the Table of Contents
Cypress End-to-End Tests
- The tests visit the Swagger API docs to verify the availability and correctness
- The tests execute and validate all CRUD operations against the API
- Install Cypress:
npm install --save-dev cypress
- Run tests with interactive Cypress GUI to select and run specific tests
npx cypress open
- OR Run tests headless and no interactive Cypress GUI
npx cypress run
- OR Run Unit tests, start the API Server, and run Cypress E2E tests in one command
npm test && node server.js && npx cypress run
⇡ Return to the Table of Contents
- CI is scheduled to run daily and will run on every push/PR
- API is deployed in Docker and health-checked ➝ Unit tests (Jest) ensure API correctness on the API server startup ➝ E2E Cypress tests validate API and Swagger live :)
- HTML reports are generated for each Cypress test run and uploaded as workflow artefacts.
- See .github/workflows/main.yml.
⇡ Return to the Table of Contents
├── .github/
└── workflows/
└── main.yml # Workflow for GitHub Actions
├── tests/
└── app.test.js # Unit tests for API
├── app.js # Express app and API logic
└── cypress/
└── e2e/
└── api_crud.cy.js # E2E tests for API and Swagger
├── package.json
├── server.js # Express app server start logic
⇡ Return to the Table of Contents
- Swap the in-memory array for a persistent database (MongoDB, PostgreSQL, etc.) as needed
- Add new models, auth, environment config, and deployment scripts per your scaling needs
⇡ Return to the Table of Contents
- Integrate API mocking for CRUD using RestAssured or WireMock and add to Github Actions workflow to showcase it as part of this repo poc/showcase.
- Integrate Jmeter performance testing for Crud and add to Github Actions workflow to showcase it as part of this repo poc/showcase.
- Integrate Cucumber BDD for the Cypress end-to-end tests
⇡ Return to the Table of Contents