chore: update readme, add architecture doc

ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# Architecture
+
+## Directory overview
+
+```
+tests/automation/
+├── setup/        # App launch and typed test fixtures
+├── utilities/    # Reusable action helpers (send message, create contact, etc.)
+├── locators/     # Page Object Model — all UI selectors
+├── constants/    # Shared test data and configuration values
+└── types/        # TypeScript type definitions
+```
+
+## Typed test builders
+
+Tests are defined using typed builder functions that handle window launch, user creation, and teardown. The function name encodes the scenario:
+
+```ts
+test_Alice_1W_Bob_1W(
+  'some test name',
+  async ({ alice, aliceWindow1, bob, bobWindow1 }) => {
+    // windows are open, users are created
+  },
+);
+```
+
+Naming convention:
+
+- User names: `Alice`, `Bob`, `Charlie`, `Dracula`
+- `1W` / `2W` = number of windows for that user; `2W` is a linked device (second window using the same recovery phrase)
+
+Teardown (force-close all windows) runs in a `finally` block. `test_Alice_1W_no_network` skips waiting for the network to be ready.
+
+All builders are in [tests/automation/setup/sessionTest.ts](tests/automation/setup/sessionTest.ts).
+
+### Test context
+
+Builders accept an optional `TestContext` object that injects conditions into the Electron process at launch:
+
+| Field                   | Effect                                                                                                                                   |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `dbCreationTimestampMs` | Sets `DB_CREATION_TIMESTAMP_MS` — mocks the account's database creation time (used to simulate account age, e.g. for donation CTA tests) |
+| `networkPageNodeCount`  | Sets `SESSION_MOCK_NETWORK_PAGE_NODE_COUNT` — mocks the node count shown on the network page (1–10)                                      |
+
+## Locators
+
+Selectors are centralised in [tests/automation/locators/index.ts](tests/automation/locators/index.ts), organised into classes by page or feature area. `testId()` targets `data-testid` attributes; `className()` and `hasText()` are also available.
+
+## Utilities
+
+Multi-step actions (send message, create contact, set disappearing messages, etc.) are in [tests/automation/utilities/](tests/automation/utilities/).
+
+## Playwright project split
+
+`playwright.config.ts` defines two projects:
+
+| Project         | Match pattern                 | Parallelism                         |
+| --------------- | ----------------------------- | ----------------------------------- |
+| Community tests | `**/*community*tests.spec.ts` | Sequential (`workers: 1`)           |
+| All other tests | everything else               | Parallel (`workersCount()` workers) |
+
+Community tests run sequentially because they share the same community server. Parallel execution causes incoming messages to trigger UI jumps that close open context menus, making tests unreliable.
+
+## Localization
+
+`tests/localization/` is a git submodule pointing to Session Desktop's localization strings. `pnpm sync` runs `sync-localization.sh`, which anchors the submodule pointer to the strings version matching the current Session Desktop build.
+
+## Maintenance notes
+
+**Locators** break when the app UI changes. Update the relevant class in [tests/automation/locators/index.ts](tests/automation/locators/index.ts).
+
+**Baseline screenshots** need updating when intentional UI changes ship. Delete the affected files in `screenshots/` and rerun the affected tests — Playwright auto-saves a new baseline when none exists. Baselines are platform-specific (`-darwin` / `-linux`); update on both platforms before committing.
+
+**Dependabot** is configured in [.github/dependabot.yml](.github/dependabot.yml)

README.md

@@ -1,55 +1,30 @@
 # Automation testing for Session Desktop
 
-This repository holds the code to do regression testing with Playwright for Session Desktop.
+This repository holds the code to run regression test for Session Desktop with Playwright.
 
-## Setup
+## Prerequisites 
 
+- Node.js 24.12.0
+- pnpm 10.28.1
+- [Session Desktop](https://github.com/session-foundation/session-desktop/) built from source
 
-`git clone https://github.com/session-foundation/session-playwright/`
+Note: The tests currently are only compatible with Linux and macOS.
 
-Install [nvm](https://github.com/nvm-sh/nvm) or [nvm for windows](https://github.com/coreybutler/nvm-windows).
+## Quick setup 
+```bash
+pnpm install --frozen-lockfile
+git submodule update --init --recursive
+```
 
-Once nvm is installed, install the node version declared in the `.nvmrc` file:
-- `nvm install` on linux/macos
-- `nvm install <specific version from the .nvmrc>` on windows
+## Environment configuration
 
-Install [pnpm](https://pnpm.io/installation):
-You can install it by running `npm install --global pnpm`, but you should read the [installation instructions](https://pnpm.io/installation) as other methods are better.
+- `cp .env.sample .env`
+- Edit the `.env` file to match your desired configuration
+- The usage of each environment variable is documented in the sample file.
 
-Install dependencies:
-- `pnpm install`
+## Running tests
 
-## Config
-
-Create your own config from the `.env.sample` and edit the values to match your environment & how you want to test.
-- `cp .env.sample .env` Copy .env.sample to .env
-- edit the `.env` file
-
-
-### Config details
-
-- `SESSION_DESKTOP_ROOT`
-  - *type*: string
-  - *default*: 1
-  - *description*: the path to the root of session-desktop to test
-- `PLAYWRIGHT_REPEAT_COUNT`
-  - *type*: number
-  - *default*: 0
-  - *description*: how many times to repeat each test. So, if a test **passed or failed** on attempt x, and our current attempt is `< PLAYWRIGHT_REPEAT_COUNT` the test will be scheduled to be run again. This can be used to debug flaky tests
-- `PLAYWRIGHT_RETRIES_COUNT`
-  - *type*: number
-  - *default*: 0
-  - *description*: the number of retries each test. i.e. if a test **failed** on attempt x, and our current attempt is `< PLAYWRIGHT_RETRIES_COUNT` the test will be scheduled to be run again. This can be used to debug flaky tests
-- `PLAYWRIGHT_WORKERS_COUNT`
-  - *type*: number
-  - *default*: 1
-  - *description*: the number of workers to start in parallel. The more, the faster the test suite is going to run, but if you hit your CPU limit they'll start to be unnecessarily flaky. Should be fine with a value between 10-20 depending on the machine.
-
-
-## Test run
-
-To run a specific test, or tests matching a string you can do so with
-`pnpm test -g "<string to match>"`.
-
-To run all the test suite, just do
-`pnpm test`.
+```bash
+pnpm test                           # Run the entire suite
+pnpm test -g "grep pattern"         # Run specific tests 
+```