> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat test plan

> QA checks for gig chats on web and mobile: creating chats, messages, photos, reactions, replies, mentions, pins, read receipts, notification settings, and the text message bridge for crew without the app.

Managers create named group chats on a gig. Crew with the app chat on mobile, managers chat on web or mobile, and crew without the app take part by text message. Read the [QA testing guide](https://docs.soundchecklive.io/qa.md) before you start, and see [Chat](https://docs.soundchecklive.io/features/chat/overview.md) for how the feature works.

## At a glance

| | |
| - | - |
| **Platforms** | Web and mobile. Text messages for crew without the app. |
| **Roles** | Manager (owner, admin, or gig coordinator) creates and manages chats. Any member sends messages. |
| **Feature flag** | `event-chats`. On for every `@soundchecklive.io` account and for listed test orgs. |
| **Build** | Ships over the air. No new native build needed. |
| **Deployed** | See [What's ready](https://docs.soundchecklive.io/qa/scope.md). |
| **Linear** | Parent work ENG-1958 and ENG-1965. Flow label `flow/chat`. |

## Before you start

* **An org with the flag on.** If the gig has no **Chats** section, confirm with the QA lead that the org has `event-chats`.
* **A published gig.** Use an active gig, not a draft, that is not the sample gig. Crew who are only invited cannot open a draft gig.
* **Staffed crew.** At least two crew members who accepted, each signed in to the app on their own device.
* **For the text message checks:** one crew member with a real mobile number and no Soundcheck account.
* **Two devices or two browsers at once** for any check where one person sends and another receives.

> [!WARNING]
>
> Chat sends pushes and texts to real people. Add only test accounts and test phone numbers to a test chat.

## Where chats live

* **Crew on mobile:** the gig's **Chats** section. Crew with no chats on the gig do not see the section.
* **Managers on mobile:** the gig's **More → Chats**.
* **Web:** the gig's **Chats** tab, and the **Chats** button in the work dock.

## In scope

### Create and manage chats

| ID | Role and surface | Steps | Expected |
| - | - | - | - |
| CHAT-01 | Manager, web and mobile | Tap **New chat**. Enter a name, pick members, and tap **Create**. | The chat opens. You are a member without picking yourself. A "started the chat" row shows. |
| CHAT-02 | Manager, web and mobile | Open the member picker. | **On this gig** lists staffed crew first. **Everyone else in the organization** is folded below. Search covers both. |
| CHAT-03 | Manager, web and mobile | Look for a person with no app and no phone number in the picker. | The person cannot be picked and shows "No app or phone number on file". |
| CHAT-04 | Manager, web and mobile | Tap **Chat with all crew** on a gig with staffed crew. | A chat named **All crew** is created with every reachable staffed crew member. Tapping the button again opens the same chat. |
| CHAT-05 | Manager, web and mobile | Staff a new crew member, then open the all-crew chat actions. | **Add 1 newly staffed crew** adds that person. |
| CHAT-06 | Crew, web and mobile | Look for **New chat** or **Chat with all crew**. | Neither shows for crew. |
| CHAT-07 | Manager, mobile | Open **Chat info**. Use **Rename chat**, **Add members**, and remove a member. | Each change saves, and a row in the thread says who renamed, added, or removed whom. |
| CHAT-08 | Manager, web | Use **Chat actions → Rename**, then add members from the members popover. | Same result as CHAT-07. |
| CHAT-09 | Manager, web and mobile | **Archive chat** and confirm. | The confirm says archiving stops text delivery. The chat leaves the list. Its pins are cleared. |
| CHAT-10 | Crew with the app, mobile | **Chat info → Leave chat**. | You leave. A "left" row shows for the others. |
| CHAT-11 | Manager not in a chat, web or mobile | Open a chat you are not a member of. | You are added as a member and start getting its notifications. |

### Messages

| ID | Role and surface | Steps | Expected |
| - | - | - | - |
| CHAT-12 | Any member, web and mobile | Send a text message. | It shows **Sending…**, then **Sent**. The other member sees it without refreshing. |
| CHAT-13 | Any member, web and mobile | Paste a message longer than 4,000 characters. | The send is refused. |
| CHAT-14 | Any member, web and mobile | Send a message with a web address, an email address, and a US phone number. | Each one is a link. On web, the web address opens in a new tab. |
| CHAT-15 | Any member, mobile | Attach a photo with **Take photo** and with **Choose photo**, with and without a caption. | The photo sends and shows in the thread on web and mobile. |
| CHAT-16 | Any member, web | Attach a photo by the attach button, by paste, and by drag and drop. | Each one sends. |
| CHAT-17 | Any member, web and mobile | Try a file that is not a photo, such as a PDF. | "Only photos can be sent in chat." |
| CHAT-18 | Any member, web and mobile | Send a photo larger than 5 MB. | The app shrinks it and sends it, or says photos can be up to 5 MB. |
| CHAT-19 | Any member, web and mobile | React to a message, then tap the same reaction chip again. | The chip appears with a count, then goes away. Five quick reactions show, and **more** opens the rest. |
| CHAT-20 | Any member, mobile | Long-press a reaction chip. | A sheet lists who reacted. |
| CHAT-21 | Any member, web and mobile | Use **Copy** on mobile or **Copy text** on web. | The text is on the clipboard. Mobile shows a **Copied** toast. |
| CHAT-22 | Author, web and mobile | **Edit** your own message. | The new text shows with **(edited)** for every member. |
| CHAT-23 | Author, web and mobile | **Delete** your own message. | The confirm warns that text-message crew already got it. The message becomes a "Message deleted" placeholder. |
| CHAT-24 | Manager, web and mobile | Open the actions on someone else's message. | No **Edit** or **Delete**. |
| CHAT-25 | Any member, web and mobile | **Reply** to a message. On mobile, also swipe right on a message. | The composer shows **Replying to** the person. The sent reply quotes the original, and tapping the quote jumps to it. |
| CHAT-26 | Any member, web and mobile | Reply to a message, then have its author delete the original. | The quote reads "Original message deleted". |
| CHAT-27 | Any member, web and mobile | Open the actions on a message. | The order is Reply, Copy, Edit, Delete, Pin or Unpin, Info. Edit and Delete show on your own messages only. Pin shows for managers only. |

### Mentions

| ID | Role and surface | Steps | Expected |
| - | - | - | - |
| CHAT-28 | Any member, web and mobile | Type `@` in the composer. | A list of the other members appears. Picking one inserts the mention. |
| CHAT-29 | Manager, web and mobile | Type `@`. | `@everyone` is offered. |
| CHAT-30 | Crew, web and mobile | Type `@`. | `@everyone` is not offered. |
| CHAT-31 | Mentioned member, web and mobile | Receive a message that mentions you. | The mention is highlighted, and the message has a tinted background. The chat list shows `@` before the unread count. |

### Pins

| ID | Role and surface | Steps | Expected |
| - | - | - | - |
| CHAT-32 | Manager, web and mobile | **Pin** a message. | A banner under the header shows the newest pin for every member. A "pinned a message" row appears. |
| CHAT-33 | Any member, web and mobile | Tap the pin banner, then **N pinned**. | Tapping the banner jumps to the message. **N pinned** opens the pinned list. |
| CHAT-34 | Manager, web and mobile | Pin a sixth message. | "This chat already has 5 pinned messages". The pinned list opens with "Unpin one first." |
| CHAT-35 | Any member, web and mobile | Dismiss the banner with ✕. | It stays hidden on that device until someone pins a newer message. |
| CHAT-36 | Manager, mobile | **Chat info → Pinned messages**, then unpin. | The message is unpinned, with **Undo** in the toast. |
| CHAT-37 | Crew, web and mobile | Open the actions on a message. | No **Pin**. Crew can view pins but not change them. |

### Read receipts and status

| ID | Role and surface | Steps | Expected |
| - | - | - | - |
| CHAT-38 | Sender, web and mobile | Send a message, then have another member open the chat. | Your latest message moves from **Sent** to **Seen by** that person. When every member has seen it, **Seen by everyone**. |
| CHAT-39 | Sender, web and mobile | Tap the status line, or use **Info**. | Lists of who has seen it, who has not, and who got it by text. |
| CHAT-40 | Crew, web and mobile | Open **Info** on someone else's message. | Not available. Info on other people's messages is for managers only. |
| CHAT-41 | Sender, mobile | Turn on airplane mode, send, then reconnect. | The message shows **Failed to send · Tap to retry**. **Retry** sends it. **Edit draft** puts the text back in the composer. |
| CHAT-42 | Sender, web | Send while the network is blocked for 15 seconds. | The message shows **Not sent** with **Retry**, **Edit**, and **Delete**. |

### Unread and scrolling

| ID | Role and surface | Steps | Expected |
| - | - | - | - |
| CHAT-43 | Any member, web and mobile | Have another member send three messages while you are out of the chat. | The chat list shows 3 unread. Your own messages never add to the count. |
| CHAT-44 | Any member, web and mobile | Open that chat. | A **New messages** divider sits above the first unread message. Web opens at the divider. Mobile opens at the newest message. |
| CHAT-45 | Any member, web and mobile | Scroll up, then have another member send messages. | A pill shows the count of new messages and jumps to the newest. |
| CHAT-46 | Any member, web and mobile | Add a member, rename, or pin. | The thread shows a row for each event. The rows send no push, no text, and no unread count. |

### Notification settings

| ID | Role and surface | Steps | Expected |
| - | - | - | - |
| CHAT-47 | Any member, mobile | Tap the bell, or **Chat info → Notifications**. | **All messages**, **Mentions only**, **Nothing**, **Mute for 1 hour**, and **Mute until the gig ends**. Saving shows an **Undo** toast. |
| CHAT-48 | Any member, web | Open the bell menu in the chat. | The same choices as mobile. |
| CHAT-49 | Any member, web and mobile | Mute a chat. | The chat list shows a muted bell and a grey unread badge. **Resume notifications** undoes it. |
| CHAT-50 | Any member, web and mobile | Open a chat on a gig that has ended. | **Mute until the gig ends** is not offered. |

### Open a chat by link

| ID | Role and surface | Steps | Expected |
| - | - | - | - |
| CHAT-51 | Chat member who is not on the gig, mobile | Tap a chat push, or open `soundcheck://chat/<chatId>`. | The chat opens with the gig title in the header. **Back** goes to Gigs. |
| CHAT-52 | Any user, mobile | Open a link to a chat that does not exist. | "Chat not found". |

## Text message crew

These checks need a real phone that receives texts, on an environment whose text-message number pool is approved for sending. Ask the QA lead which environment that is before you start.

| ID | Check | Expected |
| - | - | - |
| CHAT-53 | Add the phone-only crew member to a chat. | One welcome text names the org, chat, and gig, and says to reply STOP to leave or HELP for help. |
| CHAT-54 | Send a text message in the app. | The phone gets the message. |
| CHAT-55 | Reply from the phone. | The reply reaches the whole chat. In the app it shows a **via text** marker. |
| CHAT-56 | Send a photo in the app. | The phone gets a text saying a photo was shared and to open the Soundcheck app to see it. It may also get the photo. |
| CHAT-57 | Reply in the app to a message. | The phone gets two lines: a short quote of the original, then the reply. |
| CHAT-58 | React, edit, delete, pin, rename, and add a member in the app. | The phone gets nothing for any of these. |
| CHAT-59 | Text HELP from the phone. | One private help reply. The chat does not see it. |
| CHAT-60 | Text STOP from the phone. | The person leaves the chat. |
| CHAT-61 | Check the sender's status line in the app. | **Delivered** once the text reaches the phone. **Info** lists the person under **By text**. |

## Push notifications

These checks need a real phone or a simulator that receives pushes, and two accounts.

| ID | Check | Expected |
| - | - | - |
| CHAT-62 | Another member sends a message while the app is in the background. | One push titled with the chat name and gig, with the sender's name and text. Tapping it opens the chat. |
| CHAT-63 | Another member mentions you, or a manager uses `@everyone`. | The push says the sender mentioned you, or wrote to everyone. |
| CHAT-64 | Set the chat to **Mentions only**, then receive a plain message and a mention. | No push for the plain message. A push for the mention. A reply to your message is not a mention and sends no push. |
| CHAT-65 | Set the chat to **Nothing**, then receive a mention. | No push. |
| CHAT-66 | Turn off **Event chat messages** in **You → Settings → Notifications**. | No chat pushes for that org, whatever the per-chat setting. |
| CHAT-67 | Receive a message in the chat you have open. | No push banner. |
| CHAT-68 | React to, edit, delete, or pin a message. | No push. |

## Out of scope

Do not file these as bugs. They are not built yet.

* Direct messages between two people.
* `@crew`, `@here`, or department mentions.
* Sending PDFs or other files in chat. Use the gig's **Files**.
* Managers deleting other people's messages.
* Reactions, edits, mutes, or pins over text message (ENG-2032, ENG-2041).
* Hiding read receipts for an org (ENG-2038).
* A chat list for chat members who are not on the gig, and opening a chat by link on web (ENG-1956).
* Link previews and links for street addresses.
* Search across chats, a chat made for every gig automatically, CheckAI replies in a chat, and sending while offline.
* An app icon badge for unread chats.
* Picture messages to phones. The `event-chat-mms` flag is off, so phones get a "photo was shared" text instead.

## Known limitations

* **The `@` mark in the chat list** updates only when the list reloads.
* **The New messages divider** sits on the oldest loaded message when more than 30 are unread.
* **Add newly staffed crew** also offers people who left or were removed from the all-crew chat.
* **The all-crew chat does not follow staffing changes on its own.** A manager adds new crew with the button.
* **The existing [Chat](https://docs.soundchecklive.io/features/chat/overview.md) feature page** is the reference for how chat behaves. Where this plan and that page disagree, this plan is newer. Report the gap to the QA lead.

## For agents

* **Deep links:** `soundcheck://events/<eventId>/chats/<chatId>` opens a chat inside its gig. `soundcheck://chat/<chatId>` opens a chat by its ID.
* **Two-account checks** need two simulators, one signed in with `npm run sim:e2e-login -- --as user` and the other with `--as member`. See the [agent runbook](https://docs.soundchecklive.io/qa/agent-runbook.md).
* **API:** routes for creating, renaming, archiving, adding and removing members, and pinning return 403 for crew in the org and 404 for people outside it. With the flag off, chat routes return 404 `FEATURE_DISABLED`. List operations with `npm run api -- ops chat`.
* **The local emulator** has no photos, no real texts, and no webhooks. Run photo and text checks on a hosted environment.
* **Push type:** `event_chat_message`.
* **Analytics** (PostHog): server events `event_chat_created`, `event_chat_updated`, `event_chat_notifications_updated`, `event_chat_reaction_added`, `event_chat_message_updated`, and `event_chat_message_deleted`. Mobile and web send `event_chat_viewed`, `event_chat_message_sent`, and `event_chat_message_failed`. Mobile also sends `event_chat_seen_by_opened`. Properties are in `docs/engineering/reference/analytics-taxonomy.mdx` in the repository.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.