# Multi-User and Collaboration Testing

> **When to use**: When your application involves real-time collaboration, multi-user workflows, or any scenario where two or more users interact with the same resource simultaneously -- chat apps, shared documents, multiplayer features, admin-and-user flows.
> **Prerequisites**: [core/fixtures-and-hooks.md](fixtures-and-hooks.md), [core/configuration.md](configuration.md)

## Quick Reference

```typescript
// Two independent browser contexts in one test = two users
const alice = await browser.newContext({ storageState: "auth/alice.json" })
const bob = await browser.newContext({ storageState: "auth/bob.json" })
const alicePage = await alice.newPage()
const bobPage = await bob.newPage()

// Each operates independently — different cookies, sessions, localStorage
await alicePage.goto("/chat/room-1")
await bobPage.goto("/chat/room-1")
```

## Patterns

### Two Users in One Test via Browser Contexts

**Use when**: You need to verify that actions by one user are visible to another in real time.
**Avoid when**: You only need to test a single user's flow. One context per test is the default.

Each `browser.newContext()` creates a fully isolated session -- separate cookies, localStorage, and network state. This is how you simulate two logged-in users in a single test without launching a second browser.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("alice sends a message and bob sees it", async ({ browser }) => {
  // Create two isolated contexts
  const aliceContext = await browser.newContext({ storageState: "auth/alice.json" })
  const bobContext = await browser.newContext({ storageState: "auth/bob.json" })

  const alicePage = await aliceContext.newPage()
  const bobPage = await bobContext.newPage()

  // Both navigate to the same chat room
  await alicePage.goto("/chat/general")
  await bobPage.goto("/chat/general")

  // Alice sends a message
  await alicePage.getByRole("textbox", { name: "Message" }).fill("Hello Bob!")
  await alicePage.getByRole("button", { name: "Send" }).click()

  // Bob sees it in real time
  await expect(bobPage.getByText("Hello Bob!")).toBeVisible()

  // Alice also sees her own message
  await expect(alicePage.getByText("Hello Bob!")).toBeVisible()

  // Cleanup
  await aliceContext.close()
  await bobContext.close()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("alice sends a message and bob sees it", async ({ browser }) => {
  const aliceContext = await browser.newContext({ storageState: "auth/alice.json" })
  const bobContext = await browser.newContext({ storageState: "auth/bob.json" })

  const alicePage = await aliceContext.newPage()
  const bobPage = await bobContext.newPage()

  await alicePage.goto("/chat/general")
  await bobPage.goto("/chat/general")

  await alicePage.getByRole("textbox", { name: "Message" }).fill("Hello Bob!")
  await alicePage.getByRole("button", { name: "Send" }).click()

  await expect(bobPage.getByText("Hello Bob!")).toBeVisible()
  await expect(alicePage.getByText("Hello Bob!")).toBeVisible()

  await aliceContext.close()
  await bobContext.close()
})
```

### Multi-User Fixture for Reusability

**Use when**: Multiple tests need two-user setups. Wrap context creation in a fixture to avoid boilerplate.
**Avoid when**: Only one test needs multi-user logic.

**TypeScript**

```typescript
// fixtures.ts
import { test as base, expect, BrowserContext, Page } from "@playwright/test"

type MultiUserFixtures = {
  aliceContext: BrowserContext
  alicePage: Page
  bobContext: BrowserContext
  bobPage: Page
}

export const test = base.extend<MultiUserFixtures>({
  aliceContext: async ({ browser }, use) => {
    const context = await browser.newContext({ storageState: "auth/alice.json" })
    await use(context)
    await context.close()
  },
  alicePage: async ({ aliceContext }, use) => {
    const page = await aliceContext.newPage()
    await use(page)
  },
  bobContext: async ({ browser }, use) => {
    const context = await browser.newContext({ storageState: "auth/bob.json" })
    await use(context)
    await context.close()
  },
  bobPage: async ({ bobContext }, use) => {
    const page = await bobContext.newPage()
    await use(page)
  },
})

export { expect }
```

```typescript
// collaboration.spec.ts
import { test, expect } from "./fixtures"

test("both users see shared document title", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/docs/shared-doc")
  await bobPage.goto("/docs/shared-doc")

  await alicePage.getByRole("textbox", { name: "Title" }).fill("Project Plan")

  await expect(bobPage.getByRole("textbox", { name: "Title" })).toHaveValue("Project Plan")
})
```

**JavaScript**

```javascript
// fixtures.js
const { test: base, expect } = require("@playwright/test")

const test = base.extend({
  aliceContext: async ({ browser }, use) => {
    const context = await browser.newContext({ storageState: "auth/alice.json" })
    await use(context)
    await context.close()
  },
  alicePage: async ({ aliceContext }, use) => {
    const page = await aliceContext.newPage()
    await use(page)
  },
  bobContext: async ({ browser }, use) => {
    const context = await browser.newContext({ storageState: "auth/bob.json" })
    await use(context)
    await context.close()
  },
  bobPage: async ({ bobContext }, use) => {
    const page = await bobContext.newPage()
    await use(page)
  },
})

module.exports = { test, expect }
```

### Collaborative Editing with Conflict Detection

**Use when**: Testing real-time collaborative editors (Google Docs-style) where both users edit the same content.
**Avoid when**: Your app does not support concurrent editing.

**TypeScript**

```typescript
import { test, expect } from "./fixtures"

test("concurrent edits merge without data loss", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/docs/shared-doc")
  await bobPage.goto("/docs/shared-doc")

  // Wait for both to be connected
  await expect(alicePage.getByTestId("connection-status")).toHaveText("Connected")
  await expect(bobPage.getByTestId("connection-status")).toHaveText("Connected")

  // Alice types at the beginning
  const aliceEditor = alicePage.getByRole("textbox", { name: "Editor" })
  await aliceEditor.pressSequentially("Alice was here. ")

  // Bob types at the end (simultaneously)
  const bobEditor = bobPage.getByRole("textbox", { name: "Editor" })
  await bobEditor.press("End")
  await bobEditor.pressSequentially("Bob was here.")

  // Both edits should be visible to both users
  await expect(aliceEditor).toContainText("Alice was here.")
  await expect(aliceEditor).toContainText("Bob was here.")
  await expect(bobEditor).toContainText("Alice was here.")
  await expect(bobEditor).toContainText("Bob was here.")
})
```

**JavaScript**

```javascript
const { test, expect } = require("./fixtures")

test("concurrent edits merge without data loss", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/docs/shared-doc")
  await bobPage.goto("/docs/shared-doc")

  await expect(alicePage.getByTestId("connection-status")).toHaveText("Connected")
  await expect(bobPage.getByTestId("connection-status")).toHaveText("Connected")

  const aliceEditor = alicePage.getByRole("textbox", { name: "Editor" })
  await aliceEditor.pressSequentially("Alice was here. ")

  const bobEditor = bobPage.getByRole("textbox", { name: "Editor" })
  await bobEditor.press("End")
  await bobEditor.pressSequentially("Bob was here.")

  await expect(aliceEditor).toContainText("Alice was here.")
  await expect(aliceEditor).toContainText("Bob was here.")
  await expect(bobEditor).toContainText("Alice was here.")
  await expect(bobEditor).toContainText("Bob was here.")
})
```

### Shared State Verification (Presence, Cursors, Indicators)

**Use when**: Verifying that one user's presence or activity is reflected in the other user's UI -- online indicators, typing indicators, cursor positions.
**Avoid when**: Presence is not a feature of your app.

**TypeScript**

```typescript
import { test, expect } from "./fixtures"

test("bob sees alice typing indicator", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/chat/general")
  await bobPage.goto("/chat/general")

  // Alice starts typing
  await alicePage.getByRole("textbox", { name: "Message" }).pressSequentially("Hel", { delay: 100 })

  // Bob sees the typing indicator
  await expect(bobPage.getByText("Alice is typing...")).toBeVisible()

  // Alice stops typing — indicator disappears after debounce
  await expect(bobPage.getByText("Alice is typing...")).toBeHidden({ timeout: 5000 })
})

test("online users list updates when user joins", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/chat/general")

  // Alice sees only herself
  await expect(alicePage.getByTestId("online-users").getByText("Alice")).toBeVisible()
  await expect(alicePage.getByTestId("online-users").getByText("Bob")).toBeHidden()

  // Bob joins
  await bobPage.goto("/chat/general")

  // Alice now sees Bob in the online list
  await expect(alicePage.getByTestId("online-users").getByText("Bob")).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("./fixtures")

test("bob sees alice typing indicator", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/chat/general")
  await bobPage.goto("/chat/general")

  await alicePage.getByRole("textbox", { name: "Message" }).pressSequentially("Hel", { delay: 100 })
  await expect(bobPage.getByText("Alice is typing...")).toBeVisible()
  await expect(bobPage.getByText("Alice is typing...")).toBeHidden({ timeout: 5000 })
})

test("online users list updates when user joins", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/chat/general")
  await expect(alicePage.getByTestId("online-users").getByText("Alice")).toBeVisible()

  await bobPage.goto("/chat/general")
  await expect(alicePage.getByTestId("online-users").getByText("Bob")).toBeVisible()
})
```

### Race Condition Testing Between Users

**Use when**: You need to verify that simultaneous actions (two users clicking "buy" on the last item, or two users editing the same field) are handled correctly.
**Avoid when**: Your app has no shared mutable resources.

**TypeScript**

```typescript
import { test, expect } from "./fixtures"

test("only one user can claim the last item", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/store/limited-item")
  await bobPage.goto("/store/limited-item")

  // Both see the item is available
  await expect(alicePage.getByText("1 remaining")).toBeVisible()
  await expect(bobPage.getByText("1 remaining")).toBeVisible()

  // Both click buy at approximately the same time
  const aliceBuy = alicePage.getByRole("button", { name: "Buy now" }).click()
  const bobBuy = bobPage.getByRole("button", { name: "Buy now" }).click()
  await Promise.all([aliceBuy, bobBuy])

  // One succeeds, one fails — verify the app handles the race
  const aliceResult = await alicePage.getByTestId("purchase-result").textContent()
  const bobResult = await bobPage.getByTestId("purchase-result").textContent()

  const results = [aliceResult, bobResult]
  expect(results).toContain("Purchase successful")
  expect(results).toContain("Item no longer available")
})

test("simultaneous form submissions do not create duplicates", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/admin/settings")
  await bobPage.goto("/admin/settings")

  // Both change the same setting
  await alicePage.getByLabel("Company name").fill("Alice Corp")
  await bobPage.getByLabel("Company name").fill("Bob Inc")

  // Submit simultaneously
  await Promise.all([
    alicePage.getByRole("button", { name: "Save" }).click(),
    bobPage.getByRole("button", { name: "Save" }).click(),
  ])

  // Reload both pages — one value should win, no corruption
  await alicePage.reload()
  const finalValue = await alicePage.getByLabel("Company name").inputValue()
  expect(["Alice Corp", "Bob Inc"]).toContain(finalValue)

  // The "loser" should see a conflict notification or the updated value
  await bobPage.reload()
  await expect(bobPage.getByLabel("Company name")).toHaveValue(finalValue)
})
```

**JavaScript**

```javascript
const { test, expect } = require("./fixtures")

test("only one user can claim the last item", async ({ alicePage, bobPage }) => {
  await alicePage.goto("/store/limited-item")
  await bobPage.goto("/store/limited-item")

  await expect(alicePage.getByText("1 remaining")).toBeVisible()
  await expect(bobPage.getByText("1 remaining")).toBeVisible()

  const aliceBuy = alicePage.getByRole("button", { name: "Buy now" }).click()
  const bobBuy = bobPage.getByRole("button", { name: "Buy now" }).click()
  await Promise.all([aliceBuy, bobBuy])

  const aliceResult = await alicePage.getByTestId("purchase-result").textContent()
  const bobResult = await bobPage.getByTestId("purchase-result").textContent()

  const results = [aliceResult, bobResult]
  expect(results).toContain("Purchase successful")
  expect(results).toContain("Item no longer available")
})
```

### N Users with Dynamic Context Creation

**Use when**: You need more than two users, or the number of users is variable (load-like collaboration tests).
**Avoid when**: Two users suffice. Keep it simple.

**TypeScript**

```typescript
import { test, expect, Browser, Page } from "@playwright/test"

async function createUser(browser: Browser, name: string, room: string): Promise<Page> {
  const context = await browser.newContext({ storageState: `auth/${name}.json` })
  const page = await context.newPage()
  await page.goto(`/chat/${room}`)
  return page
}

test("five users in a chat room all see each other", async ({ browser }) => {
  const names = ["alice", "bob", "charlie", "diana", "eve"]
  const pages = await Promise.all(names.map((name) => createUser(browser, name, "team-room")))

  // First user sends a message
  await pages[0].getByRole("textbox", { name: "Message" }).fill("Hello everyone!")
  await pages[0].getByRole("button", { name: "Send" }).click()

  // All users see the message
  for (const page of pages) {
    await expect(page.getByText("Hello everyone!")).toBeVisible()
  }

  // Cleanup
  for (const page of pages) {
    await page.context().close()
  }
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

async function createUser(browser, name, room) {
  const context = await browser.newContext({ storageState: `auth/${name}.json` })
  const page = await context.newPage()
  await page.goto(`/chat/${room}`)
  return page
}

test("five users in a chat room all see each other", async ({ browser }) => {
  const names = ["alice", "bob", "charlie", "diana", "eve"]
  const pages = await Promise.all(names.map((name) => createUser(browser, name, "team-room")))

  await pages[0].getByRole("textbox", { name: "Message" }).fill("Hello everyone!")
  await pages[0].getByRole("button", { name: "Send" }).click()

  for (const page of pages) {
    await expect(page.getByText("Hello everyone!")).toBeVisible()
  }

  for (const page of pages) {
    await page.context().close()
  }
})
```

## Decision Guide

| Scenario                                    | Approach                                   | Why                                                |
| ------------------------------------------- | ------------------------------------------ | -------------------------------------------------- |
| Two users interact in real time             | Two `browser.newContext()` in one test     | Fully isolated sessions, same test timeline        |
| Same multi-user setup across many tests     | Custom fixture per user context            | Eliminates boilerplate, guarantees cleanup         |
| Testing presence/typing indicators          | Sequential actions, assert on other page   | Order matters -- act on one, assert on the other   |
| Race condition (simultaneous clicks)        | `Promise.all([action1, action2])`          | Fires both as close to simultaneously as possible  |
| Admin performs action, user sees result     | Two contexts with different `storageState` | Different auth roles, same browser instance        |
| 3+ users in one test                        | Loop with `browser.newContext()` per user  | Each context is cheap; browser is shared           |
| Cross-browser multi-user (Chrome + Firefox) | Separate browser launches in `beforeAll`   | Rarely needed; contexts within one browser suffice |

## Anti-Patterns

| Don't Do This                                            | Problem                                                  | Do This Instead                                                 |
| -------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
| Use one context with two pages for two users             | Pages in the same context share cookies and localStorage | Use `browser.newContext()` per user                             |
| Open a second browser for the second user                | Wastes memory and startup time                           | Use a second `browser.newContext()` -- contexts are lightweight |
| `await page.waitForTimeout(2000)` for real-time sync     | Arbitrary delay; flaky in CI, slow in dev                | `await expect(bobPage.getByText('msg')).toBeVisible()`          |
| Share mutable state via `let` variables between contexts | Test order and timing become implicit dependencies       | Each context is independent; assert via UI                      |
| Put multi-user setup in `beforeAll`                      | `beforeAll` cannot access `page` or `context`            | Use test-scoped fixtures or inline `browser.newContext()`       |
| Forget to close extra contexts                           | Leaks memory and may cause port exhaustion               | Always close contexts in fixture teardown or `finally`          |
| Assert on both pages without waiting                     | The second page may not have received the update yet     | Use `expect` with auto-retry on the receiving page              |

## Troubleshooting

| Symptom                                        | Cause                                                     | Fix                                                                                                           |
| ---------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Second user sees stale data                    | Context created before server state was ready             | Navigate the second page after the first user's action completes                                              |
| `storageState` file not found                  | Auth setup project has not run, or path is wrong          | Run auth setup first via `dependencies` in `playwright.config`                                                |
| Both users have the same session               | Reusing the same `storageState` file for both             | Create distinct auth state files per user role                                                                |
| Real-time updates never arrive on second page  | WebSocket/SSE connection not established before assertion | Wait for a connection indicator before asserting: `await expect(page.getByTestId('connected')).toBeVisible()` |
| Test is slow with many contexts                | Too many contexts in a single test (10+)                  | Limit to 3-5 contexts per test; use API setup to reduce page interactions                                     |
| `Promise.all` race test always has same winner | Network/event loop makes one always faster                | This is expected in testing -- assert that the app handles both outcomes, not which user wins                 |

## Related

- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) -- wrap multi-user contexts in fixtures
- [core/websockets-and-realtime.md](websockets-and-realtime.md) -- test the transport layer beneath collaboration features
- [core/test-data-management.md](test-data-management.md) -- set up shared resources (rooms, documents) before multi-user tests
- [core/configuration.md](configuration.md) -- configure `storageState` per project for different user roles