jobtrackingapp/.gsd/milestones/M001/slices/S01/S01-UAT.md

S01 UAT: Smarter Gmail import and matching

Scope

Validate that one real job workspace can:

• connect Gmail
• show ranked Gmail message/thread suggestions for that job
• import a single message or full thread into the job
• preserve Gmail thread/sender/recipient metadata in correspondence
• refresh already-linked Gmail threads and surface later inbound or user-sent replies without manual re-import

Preconditions

1. Run the app with a build that includes S01 changes.
2. Sign in as a normal local user who owns at least one job application record.
3. Choose one job with a realistic company name, recruiter email, or recruiter name so Gmail matching has meaningful context.
4. Use a Gmail account that contains at least one relevant thread for that job.
5. For the continuity test, ensure that thread can receive a new inbound reply or that you can send a reply from your Gmail account during the test.
6. Start with no browser extensions that block Google OAuth popups.

---

Test Case 1 — Connect Gmail from the job workspace

Goal: Confirm Gmail connection starts from the job correspondence workspace and returns visible connection state.

Steps

1. Open the chosen job in the job workspace/dialog.
2. Go to the Correspondence area.
3. Click Import email.
4. Open the Google tab.
5. If Gmail is not connected, click Connect Gmail.
6. Complete the Google OAuth flow in the popup.
7. Return to the job workspace.

Expected results

• The popup closes or reports success.
• The Gmail section shows the connected Gmail address.
• The Gmail tab becomes usable without a page reload.
• A Last synced timestamp or connected-state indicator is visible.

---

Test Case 2 — Ranked Gmail suggestions are job-aware and explanatory

Goal: Confirm the workspace suggests likely Gmail threads/messages for the current job and explains why.

Steps

1. Stay in the same job’s Correspondence → Google tab.
2. Wait for candidate Gmail suggestions to load automatically.
3. Review the first 3 suggested threads/messages.
4. Use the manual search box with a more specific override such as the recruiter email or a subject fragment.
5. Click Search.

Expected results

• Suggestions are scoped to the current job rather than a generic inbox list.
• Each suggested thread/message shows visible ranking context such as confidence, score, and match reasons.
• Already-linked content, if any, is marked as already linked/imported rather than presented as a fresh import with no explanation.
• Manual search override changes the candidate list without breaking the job-aware context.

Edge checks

• If the job has no good recruiter/company data, the UI should still show either fallback queries or a clear empty state rather than a broken panel.
• If no Gmail matches exist, the UI should clearly say there are no matches yet for this job/search override.

---

Test Case 3 — Import a single Gmail message into the job

Goal: Confirm single-message import attaches Gmail correspondence to the correct job and preserves metadata.

Steps

1. In the Google tab, locate a suggested Gmail message that belongs to the chosen job.
2. Click Import email for that message.
3. Return focus to the correspondence list.
4. Inspect the newly imported correspondence row.
5. Without changing jobs, try importing the exact same Gmail message again if it is still visible.

Expected results

• The imported message appears in the chosen job’s correspondence history immediately.
• The correspondence row shows the imported subject/body content.
• Gmail metadata is visible on that row, including thread id and sender/recipient labels when available.
• Re-importing the same message does not create a duplicate correspondence entry.
• The UI reports that the message was already linked or skipped on the second attempt.

---

Test Case 4 — Import an entire Gmail thread into the job

Goal: Confirm thread import brings multiple related Gmail messages into the same job and stays duplicate-safe on repeat.

Steps

1. In the Google tab, choose a suggested thread with at least 2 messages.
2. Click Import thread.
3. Inspect the correspondence list after import.
4. Count how many entries from that thread now appear on the job.
5. Trigger Import thread again for the same thread if it remains listed.

Expected results

• Multiple correspondence entries from the selected Gmail thread are attached to the same job.
• Each imported entry preserves Gmail metadata (Thread, From, To) where present.
• The import result reports imported/skipped counts.
• Repeating the thread import does not duplicate messages already attached to the job.

Edge checks

• If some messages from the thread were already imported before the thread import, only the missing messages should be added.
• If the thread is fully imported already, the result should show skipped-only behavior rather than silently doing nothing.

---

Test Case 5 — Automatic linked-thread refresh imports a later reply without manual re-import

Goal: Validate the core slice promise: once a Gmail thread is linked to a job, later replies appear on that job through refresh rather than a fresh import action.

Steps

1. Start from a job that already has at least one imported Gmail message/thread with a visible linked thread id.
2. In Gmail, send a new reply on that same thread or wait for a real inbound reply from the recruiter.
3. Return to the job workspace.
4. Reopen the job if needed, but do not use Import email or Import thread for the new reply.
5. Wait for the workspace to settle.
6. If the new reply does not appear automatically after the initial load, click Refresh linked threads once.
7. Inspect the correspondence list.

Expected results

• The workspace recognizes that the job has linked Gmail threads.
• The new reply appears under the same job without the user manually selecting the thread again from Gmail candidates.
• The new reply preserves thread continuity and sender/recipient metadata.
• The Gmail area shows a refresh summary such as imported count, linked thread count, or already-current state.
• Running refresh again immediately after a successful import should not create duplicates.

Edge checks

• Test both directions if possible:
  • recruiter → user inbound reply
  • user → recruiter sent reply from Gmail
• If there are no new messages, refresh should report that linked threads are already current rather than pretending new content arrived.

---

Test Case 6 — Failure visibility is explicit

Goal: Confirm the slice does not fail as a silent no-op.

Steps

1. Disconnect Gmail from the workspace.
2. Reopen the Gmail tab for the same job.
3. Attempt to use the Gmail area again.
4. Reconnect Gmail.
5. Open a different job with no imported Gmail thread ids.
6. Check whether linked-thread refresh controls and status remain understandable.

Expected results

• Disconnected Gmail state is explicit and actionable.
• The workspace does not pretend linked-thread refresh succeeded while disconnected.
• A job with no linked Gmail threads shows a clear “no linked threads yet” state rather than a hidden failure.
• Invalid/empty states remain distinct from successful refreshes.

---

Acceptance summary

S01 passes UAT when all of the following are true for at least one real job:

• Gmail can be connected from the correspondence workspace.
• The workspace shows sensible ranked Gmail suggestions for that job.
• Single-message and full-thread imports attach correspondence to that job and stay duplicate-safe.
• Imported correspondence visibly preserves Gmail metadata.
• A later reply on an already-linked Gmail thread appears on the job through the linked-thread refresh path without requiring the user to manually re-import the thread.
• Empty/disconnected/already-current states are visible and understandable.