update readme.md

Author: Veikkosuhonen

README.md

@@ -10,14 +10,28 @@ Some key features include:
 
 ## Development
 
+Quickstart:
+
 - Install npm, docker and docker compose
 - Clone the repository
 - Copy `.env.template` as `.env` file and fill in the required values
 - Run `npm i` and `npm start` to setup and start the development environment
 
-## Azure setup
+## Environment setup
+
+See `compose.yaml` for local development. In short, in addition to the CC server, you need
+
+- PostgreSQL (docker)
+- Redis (docker)
+- Ollama (docker)
+- Azure
+- S3
+
+### Azure
 
-Create an AI foundry resource (or something) and create deployment for the models you want to use (gpt4.1 for example). 
+Azure is used for OpenAI LLMs.
+
+Create an AI foundry resource (or something) and create deployment for the models you want to use (gpt4.1 for example).
 
 Then populate .env with the following:
 ```
@@ -26,6 +40,18 @@ AZURE_API_KEY=<asd>
 GPT_41=<name-of-the-deployment-you-created>
 ```
 
+### S3
+
+S3 is used for storing user-uploaded files and their processed versions.
+
+Create an S3 bucket and populate .env with the following:
+```
+S3_HOST=<host-url>
+S3_BUCKET=<name-of-the-bucket-you-created>
+S3_ACCESS_KEY=<access-key>
+S3_SECRET_KEY=<secret-key>
+```
+
 ## Developers: things to know
 
 ### Debugging in production
@@ -35,7 +61,7 @@ In browser console, run
 toggleDevtools()
 ```
 
-### Troubleshooting
+### Common issues
 
 Getting `Error: Cannot find module @rollup/rollup-linux-arm64-musl` on MacOS?
 This is likely because you ran `npm i` locally.
@@ -46,6 +72,43 @@ docker compose build
 
 If then you're getting `concurrently not found`, prepend the `npm run dev` script with `npm i` and run once with that.
 
-### Trivia
+## E2E Testing
+
+Playwright e2e tests are located in `e2e`. `playwright.config.ts` is also important.
+
+Run the tests with
+```bash
+npm run e2e
+```
+
+To run just one test, mark it with `.only`:
+
+```ts
+test.only('test name', async ({ page }) => {
+  // test code
+});
+```
+
+When writing new spec file, make sure to import the test function from the fixtures file, like this:
+```ts
+import { teacherTest as test } from './fixtures'
+```
+
+So that the global foreach function runs for your tests. For different user roles (`studentTest`, `teacherTest`, `adminTest`), import the corresponding test function:
+```ts
+import { studentTest as test } from './fixtures'
+```
+
+### Test setup and data
+
+Test user headers are defined in `src/shared/testData.ts`. TEST_COURSES are also defined there.
+
+Before each test, the test data of a test user is reset by calling the `/test/reset-test-data` endpoint. It is found at `src/server/routes/testUtils.ts`.
+
+When running the tests, the headers `x-test-user-idx` and `x-test-user-role` are set, defining the test user's id and iam-based role. They are read at `src/server/middleware/user.ts`.
+
+The tests are isolated so that each (should at least) modifies their own data discriminated by the user's id. This allows parallel execution.
+
+## Trivia
 
 The terms `course` and `chatInstance` refer to the same thing in the codebase. However, only `chatInstance` is correct, always prefer it.