From cf5a4b9c7d01c3dbeeda01966a7acb0371388963 Mon Sep 17 00:00:00 2001 From: Muhammed Mustafa Date: Tue, 20 Sep 2022 14:50:27 +0530 Subject: [PATCH] feat(noco-docs): Added docs for unit tests --- .../content/en/engineering/unit-test.md | 159 ++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 packages/noco-docs/content/en/engineering/unit-test.md diff --git a/packages/noco-docs/content/en/engineering/unit-test.md b/packages/noco-docs/content/en/engineering/unit-test.md new file mode 100644 index 0000000000..46cd316c18 --- /dev/null +++ b/packages/noco-docs/content/en/engineering/unit-test.md @@ -0,0 +1,159 @@ +--- +title: "Unit Test" +description: "How to write unit tests" +position: 3300 +category: "Engineering" +menuTitle: "Unit Test" +--- + +## Key points + +- We use [Mocha](https://mochajs.org/) as our test runner and [chai](https://www.chaijs.com/) as our assertion library. +- We use [Supertest](https://www.npmjs.com/package/supertest) to test our API endpoints. +- All individual unit tests are independent of each other. We don't use any shared state between tests. +- Test environment also includes `sakila` database and any change on `sakila` by a test is reverted before running other tests. +- While running unit tests, it tries to connect to mysql server running on `localhost:3306` with username `root` and password `password`(which can be configured) and if not found, it will use `sqlite` as a fallback, hence no requirement of any sql server to run tests. + +## Walk through of writing a unit test + +We will create an `Table` test suite as an example. + +### Describing test suite + +Create `Table` test suite by using `describe` function of mocha. + +```typescript +export default function () { + describe('Table', tableTests); +} +``` + +### Configure test + +We will configure `beforeEach` which is called before each test is executed. We will use `init` function from `nocodb/packages/tests/unit/init/index.ts`, which is a helper function which configures the test environment(i.e resetting state, etc.). + +`init` does the following things - + +- It initializes a `Noco` instance(reused in all tests). +- Restores `meta` and `sakila` database to its initial state. +- Creates the root user. +- Returns `context` which has `auth token` for the created user, node server instance(`app`), and `dbConfig`. + +We will use `createProject` and `createProject` factories to create a project and a table. + +```typescript +let context; + +beforeEach(async function () { + context = await init(); + + project = await createProject(context); + table = await createTable(context, project); +}); +``` + +### Test case + +We will use `it` function to create a test case. We will use `supertest` to make a request to the server. We use `expect`(`chai`) to assert the response. + +```typescript +it('Get table list', async function () { + const response = await request(context.app) + .get(`/api/v1/db/meta/projects/${project.id}/tables`) + .set('xc-auth', context.token) + .send({}) + .expect(200); + + expect(response.body.list).to.be.an('array').not.empty; +}); +``` + +### Integrating the new test suite + +We create a new file `table.test.ts` in `packages/nocodb/tests/unit/rest/tests` directory. + +```typescript +import 'mocha'; +import request from 'supertest'; +import init from '../../init'; +import { createTable, getAllTables } from '../../factory/table'; +import { createProject } from '../../factory/project'; +import { defaultColumns } from '../../factory/column'; +import Model from '../../../../src/lib/models/Model'; +import { expect } from 'chai'; + +function tableTest() { + let context; + let project; + let table; + + beforeEach(async function () { + context = await init(); + + project = await createProject(context); + table = await createTable(context, project); + }); + + it('Get table list', async function () { + const response = await request(context.app) + .get(`/api/v1/db/meta/projects/${project.id}/tables`) + .set('xc-auth', context.token) + .send({}) + .expect(200); + + expect(response.body.list).to.be.an('array').not.empty; + }); +} + +export default function () { + describe('Table', tableTests); +} +``` + +We can then import the `Table` test suite to `Rest` test suite in `packages/nocodb/tests/unit/rest/index.test.ts` file(`Rest` test suite is imported in the root test suite file which is `packages/nocodb/tests/unit/index.test.ts`). + +## Running test + +To run tests, run `npm run test:unit` in `packages/nocodb` directory. + +> NOTE: We can also run individual test by using `.only` in `describe` or `it` function and the running the test command. + +```typescript +it.only('Get table list', async () => { +``` + +## Folder structure + +The root folder for unit tests is `packages/tests/unit` + +- `rest` folder contains all the test suites for rest apis. +- `model` folder contains all the test suites for models. +- `factory` folder contains all the helper functions to create test data. +- `init` folder contains helper functions to configure test environment. +- `index.test.ts` is the root test suite file which imports all the test suites. +- `TestDbMngr.ts` is a helper class to manage test databases (i.e. creating, dropping, etc.). + +## Patterns to follow + +- **Factories** + - Use factories for create/update/delete data. No data should be directly create/updated/deleted in the test. + - While writing a factory make sure that it can be used with as less parameters as possible and use default values for other parameters. + - Use named parameters for factories. + + ``` typescript + createUser({ email, password}) + ``` + + - Use one file per factory. + +## Using sakila db + +To use sakila db use `createSakilaProject` from `factory/project` to create a project. This project will be seeded with `sakila` tables. + +## Configurations + +- For Mysql db configuration, use the following environment variables to configure. + - `DB_USER` : mysql username + - `DB_PASSWORD` : mysql password + - `DB_HOST` : mysql host + - `DB_PORT` : mysql port