Documenting with OpenAPI v2, testing locally, and testing with CI - API that use prisma and postgres.

[dearshrewdwit]

Repository: https://github.com/boolean-uk/test-prisma-ci

• has a yml file that conforms to OpenAPI v2 that documents GET /movies and POST /movies
• run npm run api-docs and view the spec.
• uses jest and supertest to codify expected behaviour of the API
• tests requires some setup - another database_url for isolating test env, and an npm script to reset the test db (any change to db schema means running this)
• run npm test to run tests
• inspect the test file - prisma doesn't have nice ways to dry test code yet, it feels a bit heavy?
• there's a github action set up to run the tests.

Intention

• students have consistency and clarity about what to build
• students practice reading and understanding API documentation
• students practice running tests/have exposure to api testing - potential extensions for students to write their own
• teachers (and students) can more easily see which students have met criteria and who has not.

Feedback requested - please add comments below.

Feel free to branch and open PRs with ideas/changes - and link PRs in comments below.

[vherus]

The initial work on this gave a great foundation to go on and has been introduced to a ci branch on the cinema API exercise: https://github.com/boolean-uk/database-cinema-booking-api/tree/ci

Some changes

• I've split the tests into three folders:
  1. main for the main branch CI to test the route included with the exercise
  2. routes for the exercise route tests, these are what students will run as they work
  3. extensions for students to add extension tests, this includes one ready made extension test
• There are now two .yml files in the GH workflows folder, one for the main branch (currently pointing to ci) and one for PR's
• API Spec has been generated and served on GitHub pages, npx redoc-cli build openapi.yml -o docs/index.html was used to generate
• All requirements & extensions are now in the API spec instead of in the repo

The reason for splitting the core & extension test suites is so students can focus on the core criteria first and get the exercise into a complete state.

The reason for splitting the main branch & core criteria tests is so we can have passing CI on main while including a complete failing test suite for the core criteria.

Todo

• [x] Add the rest of the core criteria tests based on the API spec
• [x] Extract extensions from main API Spec into a separate spec
• [x] Create a github action for extension tests
• [x] Fork and clone, checkout ci branch, complete the exercise & create a PR to upstream ci branch to test everything works as intended from the POV of a student
• [x] Update the .yml workflows to use the main branch instead of ci and merge the ci branch
• [x] Pick up Liz, go to the Winchester and have a nice cold pint while all of this blows over

[vherus]

All prisma repos need something like the below to add a query level log for students to get visibility on their queries:

const { PrismaClient } = require("@prisma/client")

let logLevel = {
    log: ['query'],
}

if (process.env.NODE_ENV === 'test') {
    logLevel = {}
}

const prisma = new PrismaClient(logLevel)

module.exports = prisma

[vherus]

All API exercises need a setup like the above cinema API exercise: https://www.notion.so/boolean/Building-APIs-eb8dfb6016344271927ac65fdfd7afa8