Acceptance Tests

Acceptance tests in the Express repository validate that the example applications work correctly end-to-end. They are located in the test/acceptance directory and use the supertest library to make real HTTP requests against the example applications and assert the responses.

How Acceptance Tests Differ from Unit Tests

Unit tests, found in the test directory, verify individual functions and modules of the core Express library in isolation. They test specific behaviors of the framework itself, such as routing logic, middleware execution, and request/response extensions.

Acceptance tests, by contrast, verify that the example applications (in the examples directory) function correctly as complete, running applications. They test the integration of Express with template engines, middleware, and other components in a realistic usage scenario. While unit tests ensure that a single function like res.send() works correctly, acceptance tests ensure that an example like examples/ejs renders the expected HTML page when a client makes an HTTP request.

Structure of Acceptance Tests

Each acceptance test file corresponds to an example application in the examples directory. The tests use the supertest library to create a request object, start the example application, and make HTTP requests to it. They then assert properties of the response, such as status codes, response body content, and headers.

The tests may import helper functions from other test files. For example, the auth-related acceptance tests may import the getCookie helper from the auth test file Acceptance Tests.

A typical acceptance test follows this pattern:

1. Import the example application module (which exports a configured Express app).
2. Create a supertest agent from the app.
3. Make an HTTP request (GET, POST, etc.) to a specific route.
4. Assert the response status, body, or headers.

The test/acceptance directory contains 18 files covering various examples Acceptance Tests.

Running the Acceptance Tests

The acceptance tests are executed as part of the standard test suite. To run all tests, including acceptance tests, use the following npm script:

npm test

This runs the test script defined in package.json, which executes the full test suite including both unit tests and acceptance tests.

To run only the acceptance tests, you can use a pattern match with the test runner. For example, if using Mocha (the test framework typically used with Express):

npx mocha test/acceptance/**/*.test.js

The CI workflow defined in .github/workflows/ci.yml runs the full test suite across multiple Node.js versions and operating systems using the npm run test-ci command .github/workflows/ci.yml:83-83.

Examples Covered by Acceptance Tests

The acceptance tests cover the following example applications (each with a corresponding test file in test/acceptance):

Each of these examples has a corresponding acceptance test that verifies the example works correctly when run as a complete application.

Development Workflow

When contributing to the Express repository, follow these conventions for acceptance tests:

1. Adding a new example: If you add a new example application in the examples directory, create a corresponding acceptance test file in test/acceptance that verifies the example works correctly.

2. Modifying an existing example: Update the corresponding acceptance test to reflect any changes in behavior or output.

3. Running lint: Before submitting changes, run npm run lint to ensure code style compliance. The CI workflow runs linting on every push .github/workflows/ci.yml:29-30.

4. Test matrix: The CI workflow runs tests on multiple Node.js versions (18 through 26) and operating systems (Ubuntu and Windows) .github/workflows/ci.yml:34-36. Ensure your changes pass on all supported platforms.

5. Code coverage: The CI workflow collects and merges code coverage reports, uploading them to Coveralls .github/workflows/ci.yml:86-97. Aim to maintain or improve coverage when adding new tests.

Related Pages

• Unit Tests
• Architecture
• Overview