Skip to content

Job application tracker and AI-powered job search assistant. Helps job seekers manage their search journey with AI resume review, job matching, task logging, and application analytics, all while keeping your data private.

test(timeline): add E2E coverage for stage-to-status and interviewer-to-contacts, add the Job Timeline help page, and fix the greenhouse runner's prisma mock

Khuram Niaz695e37456a21
diff --git a/__tests__/greenhouse-runner.spec.ts b/__tests__/greenhouse-runner.spec.ts
index fa80de3..39e907e 100644
--- a/__tests__/greenhouse-runner.spec.ts
+++ b/__tests__/greenhouse-runner.spec.ts
@@ -17,7 +17,10 @@ vi.mock("@prisma/client", () => {
location: { findUnique: vi.fn(), create: vi.fn() },
company: { findUnique: vi.fn(), create: vi.fn() },
jobSource: { findUnique: vi.fn(), create: vi.fn() },
- jobStatus: { findFirst: vi.fn(), create: vi.fn() },
+ jobStatus: { findFirst: vi.fn(), findUnique: vi.fn(), create: vi.fn() },
+ // A saved job gets its first timeline stage here too (createFirstStage).
+ jobStageType: { findUnique: vi.fn(), aggregate: vi.fn(), create: vi.fn() },
+ jobStage: { create: vi.fn() },
};
return {
PrismaClient: vi.fn(function () {
@@ -139,6 +142,17 @@ describe("runAutomation (greenhouse)", () => {
(prisma.company.findUnique as any).mockResolvedValue({ id: "co" });
(prisma.jobSource.findUnique as any).mockResolvedValue({ id: "src" });
(prisma.jobStatus.findFirst as any).mockResolvedValue({ id: "st" });
+ // resolveStageTypeForStatusId looks the status up by id, then resolves the
+ // stage type from its LABEL — an existing type, so no create path here.
+ (prisma.jobStatus.findUnique as any).mockResolvedValue({
+ id: "st",
+ label: "New",
+ });
+ (prisma.jobStageType.findUnique as any).mockResolvedValue({
+ id: "stg",
+ label: "New",
+ });
+ (prisma.jobStage.create as any).mockResolvedValue({ id: "stage1" });
(generateText as any).mockResolvedValue({
text: "SCORES: match=90 recommendation=strong match\n\n## Summary\nGreat fit",
diff --git a/e2e/fixtures.ts b/e2e/fixtures.ts
index 89d7623..3f3a36c 100644
--- a/e2e/fixtures.ts
+++ b/e2e/fixtures.ts
@@ -152,6 +152,9 @@ export type CleanupRegistry = {
automation: (name: string) => void;
contact: (name: string) => void;
contactRole: (name: string) => void;
+ // Unused today (both timeline flows pick seeded stage types), but a test
+ // that types a custom stage name would otherwise leave a permanent row.
+ jobStageType: (name: string) => void;
};
type Fixtures = {
@@ -181,6 +184,7 @@ export const test = base.extend<Fixtures>({
const automations: string[] = [];
const contacts: string[] = [];
const contactRoles: string[] = [];
+ const jobStageTypes: string[] = [];
await use({
job: (id) => jobIds.push(id),
resume: (title) => resumes.push(title),
@@ -196,6 +200,7 @@ export const test = base.extend<Fixtures>({
automation: (name) => automations.push(name),
contact: (name) => contacts.push(name),
contactRole: (name) => contactRoles.push(name),
+ jobStageType: (name) => jobStageTypes.push(name),
});
// page.request carries the session cookie; page is still alive here
// because cleanup tears down before the page fixture.
@@ -215,6 +220,7 @@ export const test = base.extend<Fixtures>({
automations,
contacts,
contactRoles,
+ jobStageTypes,
},
});
if (!res.ok()) {
diff --git a/e2e/timeline.spec.ts b/e2e/timeline.spec.ts
new file mode 100644
index 0000000..a9863a8
--- /dev/null
+++ b/e2e/timeline.spec.ts
@@ -0,0 +1,79 @@
+import { test, expect, createNewJob, uniqueName } from "./fixtures";
+import type { Page } from "@playwright/test";
+
+// Opens the Add Stage dialog and picks a seeded type. The picker is a
+// non-creatable ComboBox: filter first, then match the label exactly —
+// "Offer" would otherwise also hit "Offer Accepted".
+async function openStageDialogWith(page: Page, stageLabel: string) {
+ await page.getByTestId("timeline-add-stage-btn").click();
+ await page.getByTestId("stage-type-select").click();
+ const search = page.getByPlaceholder("Search stage");
+ await search.fill(stageLabel);
+ await page.getByRole("option", { name: stageLabel, exact: true }).click();
+ await expect(search).not.toBeVisible();
+}
+
+test("adding an Offer stage moves the job's status on the Jobs list", async ({
+ page,
+ cleanup,
+}) => {
+ const jobTitle = uniqueName("Timeline Engineer");
+ const jobId = await createNewJob(page, jobTitle, cleanup);
+
+ await page.goto(`/dashboard/myjobs/${jobId}?tab=timeline`);
+ await openStageDialogWith(page, "Offer");
+
+ await expect(
+ page.getByRole("checkbox", { name: /Set as current stage/ }),
+ ).toBeChecked();
+ await page.getByRole("button", { name: "Add Stage", exact: true }).click();
+
+ // The stepper and the history list both reflect it without a reload.
+ await expect(page.getByRole("button", { name: /^Offer/ }).first()).toBeVisible();
+ await expect(page.getByRole("tab", { name: /Timeline/ })).toContainText("2");
+
+ // ...and the derived status reached the Jobs list.
+ await page.goto("/dashboard/myjobs");
+ const row = page.getByRole("row", { name: jobTitle }).first();
+ await expect(row).toBeVisible();
+ await expect(row).toContainText("Offer");
+});
+
+test("linking an interviewer to a stage puts them on the job's Contacts tab", async ({
+ page,
+ cleanup,
+}) => {
+ const jobTitle = uniqueName("Timeline Interview");
+ const contactName = uniqueName("Priya Tester");
+ const jobId = await createNewJob(page, jobTitle, cleanup);
+
+ await page.goto(`/dashboard/myjobs/${jobId}?tab=timeline`);
+
+ // An interview stage first: the stage-scoped menu items gate on stage kind.
+ await openStageDialogWith(page, "Final / Onsite Interview");
+ await page.getByRole("button", { name: "Add Stage", exact: true }).click();
+
+ // Adding a stage does not move the selection, and the menu targets the
+ // selected stage — so pick the new one before opening it.
+ await page
+ .getByRole("button", { name: /^Final \/ Onsite Interview/ })
+ .first()
+ .click();
+
+ await page.getByTestId("update-status-menu-btn").click();
+ await page.getByRole("menuitem", { name: "Link Interviewers" }).click();
+
+ await page.getByPlaceholder("Full name").fill(contactName);
+ cleanup.contact(contactName);
+ await page.getByRole("button", { name: "Add Contact" }).click();
+ await expect(
+ page.getByLabel(new RegExp(`${contactName} is already linked`)),
+ ).toBeVisible();
+ await page.getByRole("button", { name: /^Done/ }).click();
+
+ // The job's Contacts tab is the single roster of everyone involved. Loaded
+ // fresh: JobContactsTab seeds its rows from the server prop on mount.
+ await page.goto(`/dashboard/myjobs/${jobId}?tab=contacts`);
+ await expect(page.getByText(contactName)).toBeVisible();
+ await expect(page.getByText("Interviewer")).toBeVisible();
+});
diff --git a/src/app/api/test/cleanup/route.ts b/src/app/api/test/cleanup/route.ts
index 8b72b0c..2bb3ee7 100644
--- a/src/app/api/test/cleanup/route.ts
+++ b/src/app/api/test/cleanup/route.ts
@@ -33,6 +33,7 @@ export async function POST(req: NextRequest) {
automations = [],
contacts = [],
contactRoles = [],
+ jobStageTypes = [],
}: {
jobIds?: string[];
resumes?: string[];
@@ -48,6 +49,7 @@ export async function POST(req: NextRequest) {
automations?: string[];
contacts?: string[];
contactRoles?: string[];
+ jobStageTypes?: string[];
} = await req.json();
// Delete automations before resumes: Automation.resumeId is a required FK, so
@@ -121,6 +123,9 @@ export async function POST(req: NextRequest) {
await deleteLibraryByName("location", locations, userId);
await deleteLibraryByName("activityType", activityTypes, userId);
await deleteLibraryByName("contactRole", contactRoles, userId);
+ // After the jobs above: a job's stages cascade with it, which is what frees
+ // a custom stage type. Seeded types are never registered by a test.
+ await deleteLibraryByName("jobStageType", jobStageTypes, userId);
await deleteTagsByName(tags, userId);
if (mcpTokens.length > 0) {
await prisma.mcpAccessToken.deleteMany({
@@ -156,7 +161,8 @@ type RefModel =
| "company"
| "location"
| "activityType"
- | "contactRole";
+ | "contactRole"
+ | "jobStageType";
// Count every place a Library row can still be referenced from, so we never
// delete one that another job or resume section still uses.
@@ -191,6 +197,9 @@ async function referenceCount(
(await prisma.contact.count({ where: { roleId: refId } }))
);
}
+ if (model === "jobStageType") {
+ return prisma.jobStage.count({ where: { stageTypeId: refId } });
+ }
return (
(await prisma.job.count({ where: { locationId: refId } })) +
(await prisma.workExperience.count({ where: { locationId: refId } })) +
diff --git a/src/lib/wiki/schema.ts b/src/lib/wiki/schema.ts
index 48f79d8..4ca8066 100644
--- a/src/lib/wiki/schema.ts
+++ b/src/lib/wiki/schema.ts
@@ -13,6 +13,7 @@ export const WIKI_TYPES = [
export const WIKI_FEATURES = [
"setup",
"jobs",
+ "timeline",
"contacts",
"companies",
"automations",
diff --git a/wiki/index.md b/wiki/index.md
index 91e12b3..d831666 100644
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -8,6 +8,7 @@ JobSync tracks job applications, resumes and the work you do around them. These
- [Getting Started](./getting-started.md) — create an account, connect an AI provider, add your first job, and what each area of the app is for.
- [Jobs](./jobs.md) — add jobs manually or by pasting a posting into AI chat, move them through the status workflow, edit, filter, export and delete them.
+- [Job Timeline](./timeline.md) — record each stage of a hiring process with its date, link the interviewers, and build a prep list of the questions you expect.
- [Contacts](./contacts.md) — track recruiters, interviewers and references, link them to the jobs they touched, and record how you know them.
- [Companies](./companies.md) — a company's details page with its jobs and contacts, watching a company, and why a company can't be deleted.
- [Automations](./automations.md) — set up a scheduled search over Greenhouse, Lever and Ashby company boards, fill in the filters that make it work, and handle the jobs it discovers.
diff --git a/wiki/jobs.md b/wiki/jobs.md
index 8c7faa8..541df1e 100644
--- a/wiki/jobs.md
+++ b/wiki/jobs.md
@@ -27,19 +27,23 @@ This requires an AI provider and model to be set under **Settings → AI Provide
## What do the job statuses mean?
-A job carries exactly one status from: **New**, **Draft**, **Applied**, **Interview**, **Offer**, **Offer Accepted**, **Offer Declined**, **Rejected**, **Expired** and **Archived** — *Offer Declined* for an offer you turned down, *Rejected* for one the company turned down. They are labels you move by hand, not a state machine — nothing stops you going from Interview back to Draft, and nothing changes a status on your behalf.
+A job carries exactly one status from: **New**, **Draft**, **Applied**, **Interview**, **Offer**, **Offer Accepted**, **Offer Declined**, **Rejected**, **Expired**, **Archived** and **Withdrawn** — *Offer Declined* for an offer you turned down, *Rejected* for one the company turned down, *Withdrawn* for one you pulled out of. They are labels you move by hand, not a state machine — nothing stops you going from Interview back to Draft.
+
+A job's status now follows its [timeline](./timeline.md): it is whatever the job's current stage means, so changing the status also records a stage, and moving which stage is current also moves the status.
## How do I change a job's status?
-There are two ways. In the Jobs list, click a row's status badge and pick the new status from the menu. Or open the job and use the **⋮** menu at the top-right of the job details, choosing **Change status**. Either menu lists every status with the current one greyed out, and the change saves immediately — there is no separate save step.
+There are two ways. In the Jobs list, click a row's status badge and pick the new status from the menu. Or open the job and use the **Update Status** button at the top-right of the job details, choosing **Change status**. Either menu lists every status with the current one greyed out, and the change saves immediately — there is no separate save step.
The Add Job dialog also has a Status field, so a status can be set when you first create the job or from **Edit Job** later.
+All three of those paths also append a stage to the job's [timeline](./timeline.md), so the history stays in step with the label. Picking a status the job already holds adds nothing.
+
## What is on a job's details page?
-Three parts, top to bottom. A **header row** with the job title, a `Company · Location · Job Type · Workplace` line whose company name opens the company's [details page](./companies.md), and the actions: Match with AI, Cover Letter, Edit, Delete and a **⋮** menu. Below it a **summary card** of eight facts — Status, Job Type, Salary Range, Source, Applied, AI Match, Resume and Added — with the job URL and any skill badges on a divider row underneath. Below that, five **tabs**.
+Three parts, top to bottom. A **header row** with the job title, a `Company · Location · Job Type · Workplace` line whose company name opens the company's [details page](./companies.md), and the actions: **Update Status**, Match with AI, Cover Letter, Edit, Delete and a **⋮** menu. Below it a **summary card** of eight facts — Status, Job Type, Salary Range, Source, Applied, AI Match, Resume and Added — with the job URL and any skill badges on a divider row underneath. Below that, six **tabs**.
-The tabs are **Description**, **AI Match**, **Cover Letter**, **Notes** and **[Contacts](./contacts.md)**, and all five are always there. AI Match and Cover Letter stay in the bar even when the job has neither, showing a short explanation and a button to run it — so the tab set never shifts between jobs. Notes and Contacts each carry a count badge once the job has any. Contacts lists the people linked to this job with the role each played. The tab you are on is kept in the address bar, so a refresh, a bookmark or the browser Back button lands you back on the same one.
+The tabs are **Description**, **AI Match**, **[Timeline](./timeline.md)**, **Cover Letter**, **Notes** and **[Contacts](./contacts.md)**, and all six are always there. AI Match and Cover Letter stay in the bar even when the job has neither, showing a short explanation and a button to run it — so the tab set never shifts between jobs. Timeline, Notes and Contacts each carry a count badge once the job has any. Contacts lists the people linked to this job with the role each played. The tab you are on is kept in the address bar, so a refresh, a bookmark or the browser Back button lands you back on the same one.
## How do I edit, annotate or delete a job?
diff --git a/wiki/timeline.md b/wiki/timeline.md
new file mode 100644
index 0000000..11f4deb
--- /dev/null
+++ b/wiki/timeline.md
@@ -0,0 +1,92 @@
+---
+type: how-to
+title: Job Timeline
+description: Recording how a job moved through its hiring process — the stages, when each happened, who interviewed you and which questions they asked.
+feature: timeline
+tags: [timeline, stages, job stage, interview, interview rounds, screening, onsite, offer, withdrawn, prep list, interview questions, interviewers, update status, current stage, stage history]
+aliases: [stages, job stages, interview timeline, hiring process, stage history]
+status: stable
+stale_after: 2027-09-30
+---
+
+# Job Timeline
+
+## What is the Timeline tab for?
+
+The **Timeline** tab on a job's details page is that job's record of how the hiring process actually moved — one entry per stage, each with its own date, notes and outcome. A job's [status](./jobs.md) is a single label saying where the job is *now*; the timeline is the history behind that label, and the status is derived from it.
+
+The tab shows three things. A **stepper** across the top walks the stages in order, with the current one highlighted and one greyed **Offer** step at the end if the job has not reached an offer yet. A **Stage History** list down the left carries every stage in full, including any the stepper has scrolled off. Clicking either selects a stage and opens its **detail panel** on the right, where you edit the stage, record its outcome, write notes, and — on an interview stage — see the interviewers and the prep list.
+
+A count badge on the tab tells you how many stages a job has. Every job created after this feature shipped starts with one.
+
+## How do I add a stage?
+
+Use **Add stage** at the bottom of the Stage History list, or the **Update Status** button in the job header and then **Add Stage**. Both open the same dialog.
+
+Pick a **stage** from the list — *New*, *Draft*, *Applied*, *Interview*, *1st Screening Interview*, *2nd Technical Interview*, *Final / Onsite Interview*, *Offer*, *Offer Accepted*, *Offer Declined*, *Rejected*, *Expired*, *Archived* and *Withdrawn* are set up for you — or type your own name into **Or enter a custom stage name** and choose the **parent status** it means. A custom name is saved to your Library, so the second job that reaches your *Panel Interview* just picks it from the list.
+
+**Date** and **Time** are optional, and **Notes** is free text. If the stage's parent status is *Interview*, three more fields appear: **Format**, **Duration** and **Location** — use Location for a meeting link as happily as for a street address. **Set as current stage** is ticked by default; leave it ticked when you are recording where the job is now, and untick it when you are backfilling something that already happened.
+
+Editing a stage later opens the same dialog with one extra field, **Outcome**: *Scheduled*, *Completed*, *Passed*, *Failed*, *No-show* or *Cancelled*.
+
+## How does a stage change the job's status?
+
+The current stage sets the job's status: whatever parent status that stage's type carries becomes the job's status, everywhere the job is shown. Adding a stage with **Set as current stage** ticked moves the status; ticking the box on an older stage moves it back.
+
+It works the other way round too. Changing the status from **Update Status → Change status**, from a row's status badge in the Jobs list, or from the Status field in the **Edit Job** dialog appends a new stage for that status and makes it current — so a status change never leaves the timeline behind. The appended stage has no date, because none of those places asks you for one; open it from the Timeline tab and add the date if you know it.
+
+Re-picking a status the job already holds does nothing at all. If the current stage is *2nd Technical Interview* and you pick **Interview** from a dropdown, you already are at Interview, so no second stage is added.
+
+Marking a job *Applied* or *Interview* this way also sets its **Applied** flag, and an *Applied* stage fills in the applied date if the job has none yet. A date already recorded is never overwritten.
+
+## Why does a stage show a dash instead of a date?
+
+Because that stage has no date, which is allowed. Dates are optional on every stage: a stage appended by a status change never has one, and neither does a stage you added without filling the Date field.
+
+An undated stage reads `—` in the stepper and the history list, and **No date set** in its detail panel. It also sorts to the end of the timeline rather than to the start. Open the stage and use **Edit** to add the date whenever you learn it.
+
+## How do I record who is interviewing me?
+
+Select the interview stage, then use **Link** in its **Interviewers** panel, or **Update Status → Link Interviewers**. The dialog searches your existing [contacts](./contacts.md); the **Add a new contact** box at the bottom takes a name, role and email and creates the person on the spot.
+
+Linking someone also adds them to the job's **Contacts** tab with the **Interviewer** role, so that tab stays the single roster of everyone involved in the application. The reverse is not true: the **✕** beside an interviewer unlinks them from *that stage only* and leaves the job contact link alone, because the person may hold other roles on the job.
+
+The same person can be linked to several stages of the same job, and a contact you link here is an ordinary contact afterwards — editable and searchable under **Library → Contacts** like any other.
+
+## How do I build a prep list for an interview?
+
+Select the interview stage and use **Add to Prep List**, either the button on its prep-list panel or the item in the **Update Status** menu. The dialog lists your question bank with an instant search over it; tick as many questions as you like and add them in one go.
+
+To add a question that is not in the bank yet, type it into the box at the bottom, optionally pick a **category**, and add it. It is saved to your question bank as well as to this stage's prep list, so every later job can reach it — the bank is shared, not per-job. A question added this way is banked with the placeholder answer `TBD`; fill in the real answer from the Questions page when you are ready.
+
+A question can be on the prep lists of several stages at once, and **✕** beside one removes it from this stage's list without touching the bank.
+
+## What is the difference between a question on a prep list and one marked "asked"?
+
+A prep-list question is one you *expect*; the checkbox beside it records that it was *actually asked*. Tick it during or after the interview and it saves immediately — there is no separate save step — and the panel header keeps a running `2 of 5 asked` tally.
+
+The distinction is what makes the list useful afterwards: which of the questions you prepared for came up, and which did not. Marking a question asked never changes the question itself or its answer in your bank.
+
+One knock-on effect: a question that is on any prep list cannot be deleted from the question bank. The Questions page refuses with a count of the interview stages using it. Remove it from those prep lists first, then delete.
+
+## Why are Link Interviewers and Add to Prep List greyed out?
+
+Because the stage they would act on is not an interview stage. Both items are gated on the *kind* of stage, never on its timing — an interview three weeks away is still an interview stage, and you can link its panel and prep for it from the day it is scheduled.
+
+The menu tells you which stage it is targeting and why: it reads **"Applied is not an interview stage"** when the selected stage is not one, and **"Add a stage first"** when the job has no stages at all. Both items act on the stage you have selected on the Timeline tab, falling back to the current stage — so if the job's current stage is *Applied* and you want to link an interviewer, add or select the interview stage first.
+
+A stage counts as an interview stage when its parent status is *Interview*. That is true of the three seeded interview rounds, and of any custom stage type you created under the Interview status.
+
+## Can I rename or add my own stages?
+
+Yes — **Library → Stages** holds the full list, and the stage types there are yours. **New Stage** adds one, and the **⋮** menu on a row has **Edit** to rename it or change which status it means, plus **Move Up** and **Move Down** to reorder the list that the Add Stage dialog shows you. A **Stages** column tells you how many job stages currently use each type.
+
+A stage type that is in use cannot be deleted: the tab refuses and tells you how many job stages are using it. Change or remove those stages first, then delete the type.
+
+Two near-identical names stay two separate types — *On-site* and *Onsite* are different entries, because matching folds case and accents but not punctuation. If you end up with a duplicate, rename or delete one here.
+
+## Why does a job have no timeline at all?
+
+Because it was never given a stage. The most common cause is restoring a backup taken before the timeline existed: those jobs come back with their status intact but with no stages behind it, and that is a supported state rather than an error.
+
+The Timeline tab shows **No stages recorded yet** with an **Add stage** button, and the job's status stays exactly as it is until a stage sets it. Adding the first stage starts the timeline from there; nothing is invented about the job's past.