Unit Testing

To ensure DatAscend backend services function as expected, we employ unit testing strategy using Jest and Supertest. Jest is a powerful JavaScript testing framework, while Supertest allows us to test HTTP endpoints with ease. Together, they enable us to validate both individual functionalities and API endpoints effectively.

All unit tests are located in the /tests directory within the backend folder. You can execute the tests using the following command:

npm run test

Debugging tests

For more detailed logging during test execution, using the debug npm package; you can use environment variables to control the debug output:

To enable all debug logs:
Terminal window
```
DEBUG=TESTING:* npm run test
```
To enable specific log levels (verbose, info, or error):
Terminal window
```
DEBUG=TESTING:<level>,TESTING:ERROR npm run test
```

Unit testing functionalities

In this section, we focus on testing individual functions and modules within the DatAscend backend. These tests ensure that each piece of logic works as intended in isolation.

For example, consider the following test case for a simple function should return the true if 10 < n and the distance between 10 and n:

// --- src/utils/isGreaterThanTen.js ---
module.exports = function isGreaterThanTen(n) {
  const distance = Math.abs(10 - n);
  return [distance > 0, distance];
}

The corresponding test case would look like this:

// --- tests/isGreaterThanTen.test.js ---
const isGreaterThanTen = require('../src/utils/isGreaterThanTen');

describe('Test distance from 10', () => {
  it('should return false if n is less than 10', () => {
  const [result, distance] = isGreaterThanTen(5);
  expect(result).toBe(false);
  expect(distance).toBe(5);
  });

  it('should return true if n is greater than 10', () => {
  const [result, distance] = isGreaterThanTen(15);
  expect(result).toBe(true);
  expect(distance).toBe(5);
  });

  it('should return false if n is equal to 10', () => {
  const [result, distance] = isGreaterThanTen(10);
  expect(result).toBe(false);
  expect(distance).toBe(0);
  });
});

The following guidelines should be followed when writing unit tests:

The test case should describe the functionality and all possible desired outcomes.
Should be located within the /tests directory and have the .test.js extension.
Should run within Jest environment and log with the debug npm package.
Trying to not let any open handles derivate from the test execution
Must not interact with another test cases or external services.
Also it should be runnable using the npm run test command.

Unit testing API endpoints

In this section, we focus on testing the API endpoints within the DatAscend backend. These tests ensure that the HTTP endpoints work as intended and return the expected responses.

The API should comply with the specifications outlined for the OAS3 documentation. The tests should cover all possible scenarios, including success, failure, and edge cases. As we are working with Node.js, the documentation generation to be used in Swagger UI is built automatically after the tests are executed, generating the request bodies, responses, and schemas to be used on the application.

The developer should run the tests cases for them to generate the responses based on the schema and the request bodies defined in each of the endpoints of the API. The tests exposes some methods to allow the body of the request fetching and also to generate the responses based on the schema defined in the OAS3 especification on JSON Schema Draft v5.

Some of the methods exposed by the test utils (file /test/utils.js) to follow this specification are:

```
generateDataFromProperties(Object<string, Property>): Object<string, any>
```
Generates a JSON object based on the properties defined in the request body schema. It uses the JSON Schema Draft v5 extended with a faker property to generate the data.
```
validateRequiredProperties(Object<string, Property>, Array<string>): boolean
```
Validates if the required properties are present in the object. Else, it returns false.

extractRequestProperties(Object<RequestModel>, string): { properties: Object<string, Property>, required: Array<string> }

Extracts the properties and required fields from a request model for a given media type.

```
exportResponseToOpenAPI(string, string, string, Object): boolean
```
Exports the response to the OpenAPI schema. It generates the response based on the response model and the schema name with the description.
```
exportSchema(string, Object): boolean
```
Exports the schema to the OpenAPI schema. It generates the schema based on the schema model and the schema name.

Exposing request bodies to the Swagger API endpoints

The developer must expose the request body on the file /swagger/requestBodies.json then access them from the endpoint file using a OAS3 reference as defined in Reusable bodies.

Example of a request body definition:

// UserRegister is the request body and the reference to be used in the endpoint file.
// All bodies should be on same file for the swagger to catch up the structures.
{
  "UsersRegister": {
    "description": "Register a new user",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "email",
            "password",
            "username",
            "first_name",
            "last_name"
          ],
          "properties": {
            "email": {
              "type": "string",
              "example": "any@user.com",
              "faker": "{{internet.email}}"
            },
            "password": {
              "type": "string",
              "example": "any password",
              "faker": "#A0{{internet.password}}"
            },
            "username": {
              "type": "string",
              "example": "any_username",
              "faker": "{{internet.username}}"
            },
            "first_name": {
              "type": "string",
              "example": "first_name",
              "faker": "{{person.firstName}}"
            },
            "last_name": {
              "type": "string",
              "example": "last_name",
              "faker": "{{person.lastName}}"
            }
          }
        }
      }
    }
  }
}

Example of a endpoint file using the request body:

The reference to the request body is defined in the requestBody property of the endpoint. Also the references for each response is defined in the responses property of the endpoint.

/**
 * @swagger
 * /api/v1/users/register:
 *   post:
 *     tags:
 *       - Users-Data
 *     summary: Creates a new user with the provided username, email and password
 *     description: Creates a new user with the provided username, email and password.
 *     requestBody:
 *       $ref: '#/components/requestBodies/UsersRegister'
 *     responses:
 *       201:
 *         $ref: '#/components/responses/UsersRegisterStatus201'
 *       400:
 *         $ref: '#/components/responses/UsersRegisterStatus400'
 *       409:
 *         $ref: '#/components/responses/UsersRegisterStatus409'
 *       500:
 *         $ref: '#/components/responses/UsersRegisterStatus500'
 */

Writing the test cases with the exposed request bodies

The test cases should be written using the exposed request bodies and the responses defined in the endpoint file. The test cases should be written in the /tests directory and have the .test.js extension.

Each endpoint must define its API endpoint test case, and each of the tests should follow a response type that could be returned by the endpoint. The test cases should be written using the exposed request bodies and the responses defined in the endpoint file.

Example of a test case for the endpoint /api/v1/users/register:

The only shown test case is the one that validates the response with the status code 201. The other test cases should be written following the same pattern.

// *** Importing the application, test utils and the request bodies ***

describe("Users API: /api/v1/users/register", () => {
  const endpoint = "/api/v1/users/register";

  it("[201]: should register a user correctly", async () => {
    expect(api).not.toBeNull();

    // Extracting the request properties from the request body and validating the required fields
    const { properties, required } = extractRequestProperties(bodies["UsersRegister"], "application/json");
    const valid = validateRequiredProperties(properties, required);
    expect(valid).toBe(true);

    // Generating the data based on the properties using faker.
    const data = generateDataFromProperties(properties);
    expect(typeof data).toBe("object");
    expect(data).not.toBeNull();

    logger.verbose("Registering user with the following data:");
    logger.verbose(data);

    // Sending the request to the endpoint (using Supertest module)
    const response = await api
      .post(endpoint)
      .send(data);

    logger.verbose(response.body);
    expect(response.status).toBe(201);

    // Exporting the response to the OpenAPI schema after successful test.
    const generated = exportResponseToOpenAPI(
      "UsersRegisterStatus201",             // The response name
      "UsersRegisterSuccess",               // The schema name
      "Should register a user correctly",   // The description
      response.body                         // The response to be exported.
    );
    expect(generated).toBe(true);  // Schema must be generated based on this response.
  });
});

Executing the tests and reviewing the results

The tests should be executed using the command npm run test and the results should be reviewed to ensure that all the endpoints are working as expected. The generated schemas should be reviewed to ensure that the responses are being generated correctly on the Swagger UI with OAS3.

The result of and endpoint test should look like this:

This is an example, all of the tests should pass after writing the test cases for the endpoint.

FAIL  test/endpoints/users.spec.js (13.136 s)
  Users API: /api/v1/users/register
    √ [201]: should register a user correctly (400 ms)
    √ [400]: should fail to register a user with invalid data (91 ms)
    √ [409]: should fail to register a user with a conflicting email (264 ms)
    × [500]: should fail to register a user due to internal server error (73 ms)

And after that review that the schemas are being generated correctly on the Swagger UI (bottom of the webpages).

Endpoint schema verification test case

On the file found at /tests/endpoint.spec.js there is a test case that executes and verifies the following:

The API exposes the Media Types defined in the OpenAPI definition (Example, if the API is based on REST, SOAP, etc).
All API endpoints have corresponding request body schema based on the Media Type defined before.
All request body schemas are OA3/JSON Schema Draft v5 compliant.
All API endpoints have corresponding response definition based on the Media Type defined before.
All response definitions have a corresponding named schema on JSON Schema Draft v5.
All API Schemas are OA3/JSON Schema Draft v5 compliant.

This test case should be executed after all the endpoint test cases are written and executed to ensure that the API is compliant with the OpenAPI specification. Also it lists the coverage of the API endpoints and the schemas defined on the API and hit the missing parts as error logs.

An example of the output of the test case is shown below:

This is an incremental update that changes each time a new test case is written on the endpoint files.

FAIL  test/endpoint.spec.js
  API Endpoints Schema Validation
    √ should validate that the API exposes the Media Types defined in the OpenAPI definition (4 ms)
    × should validate that all API endpoints have corresponding request body schema (19 ms)
    √ should validate that all request body schemas are OA3/JSON Schema compliant (51 ms)
    × should validate that all API endpoints have corresponding response definition (85 ms)
    √ should validate that all response definitions have a corresponding schema (6 ms)
    √ should validate that all API Schemas are OA3/JSON Schema compliant (33 ms)