reorganize docs

documentation/devops/commands.md

@@ -0,0 +1,95 @@
+# npm commands
+
+## Initialization
+
+- `setup`
+  - Installs node_modules to project root, backend and frontend
+  - Sets up Prisma in backend
+  - Creates all config files
+- `config:all`
+  - Creates all config files: `.dev.env`, `.anon.env` and `.test.env`
+
+## Running the application
+
+- `start`
+  - Runs the application in the production environment
+  - Opens backend, frontend and a MariaDB database (initialized from `data` directory)
+  - Utilizes `.env`
+- `start:anon`
+  - Runs the application in dev environment
+  - Opens backend, frontend, phpMyAdmin and a MariaDB database (initialized from `test_data` directory)
+  - Utilizes `.anon.env`
+- `dev`
+  - Runs the application in development environment
+  - Enables hotswap (docker compose doesn't need to be restarted on changes inside `backend/src` or `frontend/src`)
+    - Note: When editing for example `package.json` the docker needs to be manually restarted.
+  - Opens backend, frontend, phpMyAdmin, and a MariaDB database (initialized from `data` directory)
+  - Utilizes `.dev.env`
+  - To create test users visit `http://localhost:4000/test/create-test-users`
+
+## Testing
+
+- `test:api`
+  - Runs tests for backend API
+  - Tests are located in `backend/src/api-tests`
+  - Tests are executed inside Docker
+  - Requires a database running with (preferrably, see last point) `test_data`
+  - Utilizes `.test.env`
+  - Anon version of the database is recommended be used by these tests
+  - Resets the database with `test_data` multiple times!
+- `test:api:local`
+  - Same as `test:api` but tests are executed locally
+- `test:e2e`
+  - Runs e2e tests with cypress
+  - Tests are located in `cypress/e2e`
+  - Tests are executed inside Docker
+  - Requires backend, frontend and database (with preferably `test_data`, see last point) to be running
+    - Expects to find frontend at `<baseUrl>` defined in `cypress/config.js`
+    - Expects to find database reset API-point at `<databaseResetUrl>` defined in `cypress.config.js`
+    - Both can be also defined as a environment variable
+  - Resets the database with `test_data` multiple times!
+- `test:e2e:local`
+  - Same as `test:e2e` but tests are executed locally
+  - Change the browser by running `npm run test:e2e:local -- --browser <YOUR_BROWSER_NAME>`
+- `test:unit`
+  - Runs all unit tests defined in `backend/src/unit-tests` and `frontend/src/tests`
+  - Doesn't require containers running
+  - Executed locally
+- `test:{api,e2e}:windows`
+  - Executes api or e2e command with (supposed) Windows support
+  - Not actually tested on Windows: "should work"
+  - For `api-tests` to work with Windows: inside `.test.env`, you need to change all instances of `localhost` to `host.docker.internal`.
+    - These include `MARIADB_HOST`, `DATABASE_URL` and `LOG_DATABASE_URL`.
+  - A short script that should do the same: `sed -i -e s|localhost|host.docker.internal|g .test.env`
+
+## Utilities
+
+- `check`
+  - Runs linting and typescript checking for backend, frontend and cypress
+- `anon:down`
+  - Closes all docker containers running anon versions
+  - REMOVES `nowdb-db-anon` VOLUME PERMANENTLY
+    - This is usually not a problem as the normal development environment uses a different volume
+- `dev:down`
+  - Closes all docker containers running dev versions
+  - REMOVES `nowdb-db-dev` VOLUME PERMANENTLY
+- `clean`
+  - Removes all node_modules, build directories, prisma's autogenerated files, .nyc_output and coverage directories
+- `coverage`
+  - Creates coverage report based on `.nyc_output`
+  - Replaces the incorrect paths of the files from the path inside Docker container to the current working directory (`$PWD`)
+  - Automatically run by `e2e` each time
+- `coverage:report`
+  - Alias to `coverage` for cypress to create coverage while running tests
+  - https://github.com/cypress-io/code-coverage?tab=readme-ov-file#custom-nyc-command
+
+### Be aware
+
+- Weird problems with docker?
+
+  - Add `-- --build` after for example `npm run start:anon` to force rebuilding all containers
+  - Sometimes docker doesn't rebuild containers when needed and it leads to hard-to-find bugs
+
+- Difference between `cmd1 && cmd2` and `cmd1; cmd2`
+  - `&&`: `cmd2` is executed only when `cmd1` returns 0 (=is succesful)
+  - `;`: `cmd2` is always executed (after `cmd1`)