boba-backend

Routes Structure

Each REST route in the server is defined through the same folders structure:

• A top-level folder corresponding to the name of the route (e.g. boards/, posts/, users/)

  • A sql/ folder, containing .sql files for larger queries, and an index.ts file that encapsulates these files, and exports variables and methods resolving to SQL queries. These should be, mostly, self-contained logical units corresponding to common DB operations.

    Note: some methods build queries dynamically for efficiency (e.g. turning what would be repeated calls for “insert a tag in a db” method into a single statement). This is not (and should never be) done by concatenating strings. Instead, we use pg-promise helpers to ensure any dynamic query is built as a “prepared statement”.

  • A queries.ts file, containing the interface between the database and the final REST API routes. Methods in this file usually combine multiple queries exported by sql/index.ts into a single operation.

    Note: some of these methods are imported by routes.ts files in other routes. This is not generally discouraged, but queries should be placed within the route that is semantically closest to their usage (e.g. a query to retrieve board permissions should be placed in the boards/ route, even if it might also be used to check user permissions in posts/). Your best judgement might be required.

  • A routes.ts file which exposes an express.Router object representing the route. Endpoints are attached to the route via either the router.get (data fetch) or the router.post (data insert/update) methods. The isLoggedIn middleware is available for queries dependent on user identification. Each route in the routes.ts file relies on one or more methods in queries.ts to expose functionality through REST endpoints. It also takes care of checking the validity of users inputs, communicating errors through the appropriate HTTP Status Codes.

  • A route should also contain a tests/ folder for tests. These are automatically picked up by mocha (our tests suite) when running the appropriate commands. Tests are mostly done at the queries.ts level, even though more routes.ts tests should be likely written. When at test file becomes too long, it should be separated in logical units (e.g. boards/tests/permissions.test.ts, boards/tests/notifications.test.ts).

Routes added to all-routes.ts are automatically picked up by the server upon start-up.

How to Run Tests

To run tests, you will first need to start the test DB using yarn run start-db. You can then run the tests in watch mode (which automatically reruns tests as you update the code) by running yarn run test:watch in a separate terminal tab. The tests will print a lot of debug logs, followed by a count of passed and failed cases, and a list of AssertionsErrors for those that didn’t succeed. AssertionsErrors indicate that there was a mismatch between the data that the test expected to encounter, and what was actually encountered.

IMPORTANT: the frontend and the tests act on the same database. If you’ve been using a frontend connected to your local dev server to test things out, then some tests might fail that aren’t meant to. Before running tests, make sure to use CTRL+C to stop your db, and run yarn run start-db again.

Using postman for REST API testing