From 2a1dd481e9c4d385193392ef194e81e46f524890 Mon Sep 17 00:00:00 2001
From: Ajith KV <ajith.jaban@gmail.com>
Date: Thu, 23 Jul 2026 23:24:03 +0530
Subject: [PATCH] test(playwright): add agent onboarding and inbox creation UI
 tests (#14707)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds E2E UI tests for two core Phase 2 flows, building on the Playwright
setup from #13578.

**Agent onboarding** — validates the Agents settings page, Add Agent
modal elements, form validation (name + email required, submit disabled
until valid), and cancel behaviour.

**Inbox creation** — walks through the full API channel inbox creation
journey: channel selection → form fill → agent assignment → finish
screen.

## What changed

New UI component objects (`tests/playwright/components/ui/`):
- `agent-page.component.ts`
- `add-agent-modal.component.ts`
- `add-agents-form.component.ts`
- `settings-inbox-page.component.ts`
- `channel-selector.component.ts`
- `api-channel-form.component.ts`
- `finish-setup.component.ts`

New test specs (`tests/playwright/tests/e2e/ui/`):
- `agent-onboarding-flow-ui-validation.spec.ts`
- `inbox-creation-flow.spec.ts`

Updated `components/ui/index.ts` barrel export to include all new
components.

## How to test

```bash
cd tests/playwright
npx playwright test tests/e2e/ui/
```

All 5 tests pass locally (3 login + 2 new flows).

Closes part of the Phase 2 scope from the [Playwright E2E discussion
#13500](https://github.com/orgs/chatwoot/discussions/13500).

---------

Co-authored-by: Sony Mathew <sony@chatwoot.com>
Co-authored-by: Sony Mathew <2040199+sony-mathew@users.noreply.github.com>
---
 .../dashboard/settings/inbox/AddAgents.vue    |   1 +
 .../ui/add-agent-modal.component.ts           |  61 +++++++++++
 .../ui/add-agents-form.component.ts           |  73 +++++++++++++
 .../components/ui/agent-page.component.ts     |  35 ++++++
 .../ui/api-channel-form.component.ts          |  41 +++++++
 .../ui/channel-selector.component.ts          |  25 +++++
 .../components/ui/finish-setup.component.ts   |  32 ++++++
 tests/playwright/components/ui/index.ts       |   7 ++
 .../ui/settings-inbox-page.component.ts       |  57 ++++++++++
 ...gent-onboarding-flow-ui-validation.spec.ts |  60 ++++++++++
 .../tests/e2e/ui/inbox-creation-flow.spec.ts  | 103 ++++++++++++++++++
 11 files changed, 495 insertions(+)
 create mode 100644 tests/playwright/components/ui/add-agent-modal.component.ts
 create mode 100644 tests/playwright/components/ui/add-agents-form.component.ts
 create mode 100644 tests/playwright/components/ui/agent-page.component.ts
 create mode 100644 tests/playwright/components/ui/api-channel-form.component.ts
 create mode 100644 tests/playwright/components/ui/channel-selector.component.ts
 create mode 100644 tests/playwright/components/ui/finish-setup.component.ts
 create mode 100644 tests/playwright/components/ui/settings-inbox-page.component.ts
 create mode 100644 tests/playwright/tests/e2e/ui/agent-onboarding-flow-ui-validation.spec.ts
 create mode 100644 tests/playwright/tests/e2e/ui/inbox-creation-flow.spec.ts

diff --git a/app/javascript/dashboard/routes/dashboard/settings/inbox/AddAgents.vue b/app/javascript/dashboard/routes/dashboard/settings/inbox/AddAgents.vue
index 8be54e19b..47ff4c221 100644
--- a/app/javascript/dashboard/routes/dashboard/settings/inbox/AddAgents.vue
+++ b/app/javascript/dashboard/routes/dashboard/settings/inbox/AddAgents.vue
@@ -103,6 +103,7 @@ export default {
           <label :class="{ error: v$.selectedAgentIds.$error }">
             {{ $t('INBOX_MGMT.ADD.AGENTS.TITLE') }}
             <div
+              data-testid="agent-selector"
               class="rounded-xl outline outline-1 -outline-offset-1 outline-n-weak hover:outline-n-strong px-2 py-2"
             >
               <TagInput
diff --git a/tests/playwright/components/ui/add-agent-modal.component.ts b/tests/playwright/components/ui/add-agent-modal.component.ts
new file mode 100644
index 000000000..67c5c2894
--- /dev/null
+++ b/tests/playwright/components/ui/add-agent-modal.component.ts
@@ -0,0 +1,61 @@
+import { Page } from '@playwright/test';
+
+export class AddAgentModal {
+  private page: Page;
+
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  getModalTitle() {
+    return this.page.locator('[data-test-id="modal-header-title"]');
+  }
+
+  getAgentNameInput() {
+    return this.page.getByRole('textbox', { name: 'Agent Name' });
+  }
+
+  getEmailInput() {
+    return this.page.getByRole('textbox', { name: 'Email Address' });
+  }
+
+  getRoleCombobox() {
+    return this.page.getByRole('combobox', { name: 'Role' });
+  }
+
+  getSubmitButton() {
+    return this.page.locator('form').getByRole('button', { name: 'Add Agent' });
+  }
+
+  getCancelButton() {
+    return this.page.getByRole('button', { name: 'Cancel' });
+  }
+
+  getSuccessMessage() {
+    return this.page.getByText('Agent added successfully');
+  }
+
+  async fillAgentName(name: string) {
+    await this.getAgentNameInput().fill(name);
+    await this.page.waitForTimeout(1000);
+  }
+
+  async fillEmail(email: string) {
+    await this.getEmailInput().fill(email);
+    await this.page.waitForTimeout(1000);
+  }
+
+  async submitForm() {
+    await this.getSubmitButton().click();
+  }
+
+  async cancelForm() {
+    await this.getCancelButton().click();
+  }
+
+  async createAgent(name: string, email: string) {
+    await this.fillAgentName(name);
+    await this.fillEmail(email);
+    await this.submitForm();
+  }
+}
diff --git a/tests/playwright/components/ui/add-agents-form.component.ts b/tests/playwright/components/ui/add-agents-form.component.ts
new file mode 100644
index 000000000..9257a4283
--- /dev/null
+++ b/tests/playwright/components/ui/add-agents-form.component.ts
@@ -0,0 +1,73 @@
+import { Page } from '@playwright/test';
+
+export class AddAgentsForm {
+  constructor(private page: Page) {}
+
+  getPageHeading() {
+    return this.page
+      .locator('form')
+      .getByRole('heading', { name: 'Agents', level: 2, exact: true });
+  }
+
+  getAgentDropdown() {
+    return this.page.getByPlaceholder('Pick agents for the inbox');
+  }
+
+  getAgentSelector() {
+    return this.page.getByTestId('agent-selector');
+  }
+
+  getAgentOption(agentName: string) {
+    return this.getAgentSelector().getByRole('button', {
+      name: agentName,
+      exact: true,
+    });
+  }
+
+  getDropdownButtons() {
+    return this.getAgentSelector().getByRole('button');
+  }
+
+  getSubmitButton() {
+    return this.page.getByRole('button', { name: 'Add agents' });
+  }
+
+  async openAgentDropdown() {
+    await this.getAgentDropdown().click();
+  }
+
+  async selectAgent(agentName: string) {
+    await this.openAgentDropdown();
+    await this.getAgentOption(agentName).waitFor({ state: 'visible' });
+    await this.getAgentOption(agentName).click();
+  }
+
+  async selectAgentByIndex(index: number = 0) {
+    await this.openAgentDropdown();
+    const buttons = this.getDropdownButtons();
+    await buttons.first().waitFor({ state: 'visible' });
+    await buttons.nth(index).click();
+  }
+
+  async closeDropdown() {
+    await this.page.keyboard.press('Escape');
+  }
+
+  async submitForm() {
+    await this.getSubmitButton().click();
+  }
+
+  async addAgents(agentNames: string[]) {
+    for (const agentName of agentNames) {
+      await this.selectAgent(agentName);
+    }
+    await this.closeDropdown();
+    await this.submitForm();
+  }
+
+  async addFirstAgent() {
+    await this.selectAgentByIndex(0);
+    await this.closeDropdown();
+    await this.submitForm();
+  }
+}
diff --git a/tests/playwright/components/ui/agent-page.component.ts b/tests/playwright/components/ui/agent-page.component.ts
new file mode 100644
index 000000000..034987732
--- /dev/null
+++ b/tests/playwright/components/ui/agent-page.component.ts
@@ -0,0 +1,35 @@
+import { Page } from '@playwright/test';
+
+export class AgentPage {
+  private page: Page;
+
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  async navigate(accountId: number = 1) {
+    await this.page.goto(`/app/accounts/${accountId}/settings/agents/list`);
+  }
+
+  getPageHeading() {
+    return this.page.getByRole('heading', { name: 'Agents', level: 1 });
+  }
+
+  getDescriptionText() {
+    return this.page.getByText(
+      'An agent is a member of your customer support team who can view and respond to user messages.'
+    );
+  }
+
+  getLearnLink() {
+    return this.page.getByRole('link', { name: 'Learn about user roles' });
+  }
+
+  getAddAgentButton() {
+    return this.page.getByRole('button', { name: 'Add Agent' });
+  }
+
+  async openAddAgentModal() {
+    await this.getAddAgentButton().click();
+  }
+}
diff --git a/tests/playwright/components/ui/api-channel-form.component.ts b/tests/playwright/components/ui/api-channel-form.component.ts
new file mode 100644
index 000000000..e9a98e8cd
--- /dev/null
+++ b/tests/playwright/components/ui/api-channel-form.component.ts
@@ -0,0 +1,41 @@
+import { Page } from '@playwright/test';
+
+export class ApiChannelForm {
+  constructor(private page: Page) {}
+
+  getChannelNameInput() {
+    return this.page.getByRole('textbox', { name: 'Channel Name' });
+  }
+
+  getWebhookUrlInput() {
+    return this.page.getByRole('textbox', { name: 'Webhook URL' });
+  }
+
+  getSubmitButton() {
+    return this.page.getByRole('button', { name: 'Create API Channel' });
+  }
+
+  async fillChannelName(name: string) {
+    await this.getChannelNameInput().fill(name);
+  }
+
+  async fillWebhookUrl(url: string) {
+    await this.getWebhookUrlInput().fill(url);
+  }
+
+  async submitForm() {
+    await this.getSubmitButton().click();
+  }
+
+  async createApiChannel(channelName: string, webhookUrl?: string) {
+    await this.fillChannelName(channelName);
+    if (webhookUrl) {
+      await this.fillWebhookUrl(webhookUrl);
+    }
+    await this.submitForm();
+  }
+
+  getValidationError() {
+    return this.page.locator('.message, .error-message').first();
+  }
+}
diff --git a/tests/playwright/components/ui/channel-selector.component.ts b/tests/playwright/components/ui/channel-selector.component.ts
new file mode 100644
index 000000000..8d2fe285e
--- /dev/null
+++ b/tests/playwright/components/ui/channel-selector.component.ts
@@ -0,0 +1,25 @@
+import { Page } from '@playwright/test';
+
+export class ChannelSelector {
+  constructor(private page: Page) {}
+
+  getPageHeading() {
+    return this.page.getByRole('heading', { name: /choose channel/i });
+  }
+
+  getApiChannelCard() {
+    return this.page.getByRole('button', { name: /API.*Make a custom channel/i });
+  }
+
+  getWebsiteChannelCard() {
+    return this.page.getByRole('button', { name: /Website.*Create a live-chat widget/i });
+  }
+
+  async selectApiChannel() {
+    await this.getApiChannelCard().click();
+  }
+
+  async selectWebsiteChannel() {
+    await this.getWebsiteChannelCard().click();
+  }
+}
diff --git a/tests/playwright/components/ui/finish-setup.component.ts b/tests/playwright/components/ui/finish-setup.component.ts
new file mode 100644
index 000000000..7021011f4
--- /dev/null
+++ b/tests/playwright/components/ui/finish-setup.component.ts
@@ -0,0 +1,32 @@
+import { Page } from '@playwright/test';
+
+export class FinishSetup {
+  constructor(private page: Page) {}
+
+  getPageHeading() {
+    return this.page.getByRole('heading', {
+      name: 'Your Inbox is ready!',
+      exact: true,
+    });
+  }
+
+  getGoToInboxButton() {
+    return this.page.getByRole('button', { name: /go to inbox|view inbox/i });
+  }
+
+  getMoreSettingsButton() {
+    return this.page.getByRole('button', { name: /more settings|settings/i });
+  }
+
+  getWebhookUrl() {
+    return this.page.locator('code, pre').filter({ hasText: /http/i }).first();
+  }
+
+  async goToInbox() {
+    await this.getGoToInboxButton().click();
+  }
+
+  async goToSettings() {
+    await this.getMoreSettingsButton().click();
+  }
+}
diff --git a/tests/playwright/components/ui/index.ts b/tests/playwright/components/ui/index.ts
index 82366bc05..76c824a6a 100644
--- a/tests/playwright/components/ui/index.ts
+++ b/tests/playwright/components/ui/index.ts
@@ -1 +1,8 @@
 export { Login } from './login.component';
+export { AgentPage } from './agent-page.component';
+export { AddAgentModal } from './add-agent-modal.component';
+export { AddAgentsForm } from './add-agents-form.component';
+export { SettingsInboxPage } from './settings-inbox-page.component';
+export { ChannelSelector } from './channel-selector.component';
+export { ApiChannelForm } from './api-channel-form.component';
+export { FinishSetup } from './finish-setup.component';
diff --git a/tests/playwright/components/ui/settings-inbox-page.component.ts b/tests/playwright/components/ui/settings-inbox-page.component.ts
new file mode 100644
index 000000000..af9b97f99
--- /dev/null
+++ b/tests/playwright/components/ui/settings-inbox-page.component.ts
@@ -0,0 +1,57 @@
+import { Page } from '@playwright/test';
+
+type DashboardApi = {
+  delete: (url: string) => Promise<unknown>;
+  get: (url: string) => Promise<{
+    data: {
+      payload: Array<{ id: number }>;
+    };
+  }>;
+};
+
+export class SettingsInboxPage {
+  constructor(private page: Page) {}
+
+  async navigate(accountId: number = 1) {
+    await this.page.goto(`/app/accounts/${accountId}/settings/inboxes/list`);
+  }
+
+  getAddInboxButton() {
+    return this.page.getByRole('link', { name: 'Add Inbox' });
+  }
+
+  async clickAddInboxButton() {
+    await this.getAddInboxButton().click();
+  }
+
+  getPageHeading() {
+    return this.page.getByRole('heading', { name: /inboxes/i });
+  }
+
+  async deleteInbox(accountId: number, inboxId: number) {
+    await this.page.evaluate(
+      async ({ accountId: currentAccountId, inboxId: currentInboxId }) => {
+        const api = (window as typeof window & { axios: DashboardApi }).axios;
+        await api.delete(
+          `/api/v1/accounts/${currentAccountId}/inboxes/${currentInboxId}`
+        );
+      },
+      { accountId, inboxId }
+    );
+  }
+
+  async isInboxPresent(accountId: number, inboxId: number) {
+    return this.page.evaluate(
+      async ({ accountId: currentAccountId, inboxId: currentInboxId }) => {
+        const api = (window as typeof window & { axios: DashboardApi }).axios;
+        const response = await api.get(
+          `/api/v1/accounts/${currentAccountId}/inboxes`
+        );
+        return response.data.payload.some(
+          inbox => inbox.id === currentInboxId
+        );
+      },
+      { accountId, inboxId }
+    );
+  }
+}
diff --git a/tests/playwright/tests/e2e/ui/agent-onboarding-flow-ui-validation.spec.ts b/tests/playwright/tests/e2e/ui/agent-onboarding-flow-ui-validation.spec.ts
new file mode 100644
index 000000000..49bda0638
--- /dev/null
+++ b/tests/playwright/tests/e2e/ui/agent-onboarding-flow-ui-validation.spec.ts
@@ -0,0 +1,60 @@
+import { test, expect } from '@playwright/test';
+import { AddAgentModal, AgentPage, Login } from '@components/ui';
+
+const TEST_EMAIL = process.env.TEST_USER_EMAIL || 'admin@chatwoot.com';
+const TEST_PASSWORD = process.env.TEST_USER_PASSWORD || 'Password123@#';
+
+test.describe('Agent Onboarding - UI', () => {
+  let loginComponent: Login;
+  let agentPage: AgentPage;
+  let addAgentModal: AddAgentModal;
+
+  test.beforeEach(async ({ page }) => {
+    loginComponent = new Login(page);
+    agentPage = new AgentPage(page);
+    addAgentModal = new AddAgentModal(page);
+
+    await loginComponent.navigate();
+    await loginComponent.login(TEST_EMAIL, TEST_PASSWORD);
+
+    await expect(page).toHaveURL(/\/app\/accounts\/\d+\/dashboard/);
+    const accountId = Number(page.url().match(/\/app\/accounts\/(\d+)\//)![1]);
+    await agentPage.navigate(accountId);
+  });
+
+  test('should validate all UI elements on agents page', async () => {
+    await expect(agentPage.getPageHeading()).toBeVisible();
+    await expect(agentPage.getDescriptionText()).toBeVisible();
+
+    const learnLink = agentPage.getLearnLink();
+    await expect(learnLink).toBeVisible();
+    await expect(learnLink).toHaveAttribute('href', 'https://chwt.app/hc/agents');
+
+    await expect(agentPage.getAddAgentButton()).toBeVisible();
+    await agentPage.openAddAgentModal();
+
+    await expect(addAgentModal.getModalTitle()).toBeVisible();
+    await expect(addAgentModal.getModalTitle()).toHaveText('Add agent to your team');
+
+    await expect(addAgentModal.getAgentNameInput()).toBeVisible();
+    await expect(addAgentModal.getEmailInput()).toBeVisible();
+    await expect(addAgentModal.getRoleCombobox()).toBeVisible();
+    await expect(addAgentModal.getSubmitButton()).toBeVisible();
+    await expect(addAgentModal.getCancelButton()).toBeVisible();
+
+    await expect(addAgentModal.getSubmitButton()).toBeDisabled();
+
+    await addAgentModal.getAgentNameInput().fill('Test');
+    await expect(addAgentModal.getSubmitButton()).toBeDisabled();
+
+    await addAgentModal.getAgentNameInput().clear();
+    await addAgentModal.getEmailInput().fill('test@example.com');
+    await expect(addAgentModal.getSubmitButton()).toBeDisabled();
+
+    await addAgentModal.getAgentNameInput().fill('Test');
+    await expect(addAgentModal.getSubmitButton()).toBeEnabled();
+
+    await addAgentModal.cancelForm();
+    await expect(addAgentModal.getModalTitle()).toBeHidden();
+  });
+});
diff --git a/tests/playwright/tests/e2e/ui/inbox-creation-flow.spec.ts b/tests/playwright/tests/e2e/ui/inbox-creation-flow.spec.ts
new file mode 100644
index 000000000..bdd1d4926
--- /dev/null
+++ b/tests/playwright/tests/e2e/ui/inbox-creation-flow.spec.ts
@@ -0,0 +1,103 @@
+import { test, expect } from '@playwright/test';
+import {
+  AddAgentsForm,
+  ApiChannelForm,
+  ChannelSelector,
+  FinishSetup,
+  Login,
+  SettingsInboxPage,
+} from '@components/ui';
+
+const TEST_EMAIL = process.env.TEST_USER_EMAIL || 'admin@chatwoot.com';
+const TEST_PASSWORD = process.env.TEST_USER_PASSWORD || 'Password123@#';
+
+test.describe('Inbox Creation - UI Flow', () => {
+  const testInbox = {
+    name: `Test Inbox ${Date.now()}`,
+    webhookUrl: 'https://example.com/webhook',
+  };
+
+  let accountId: number | undefined;
+  let inboxId: number | undefined;
+
+  test.beforeEach(() => {
+    accountId = undefined;
+    inboxId = undefined;
+  });
+
+  test.afterEach(async ({ page }) => {
+    const currentAccountId = accountId;
+    const currentInboxId = inboxId;
+    if (!currentAccountId || !currentInboxId) {
+      return;
+    }
+
+    const settingsInboxPage = new SettingsInboxPage(page);
+    await settingsInboxPage.deleteInbox(currentAccountId, currentInboxId);
+    await expect
+      .poll(
+        () =>
+          settingsInboxPage.isInboxPresent(currentAccountId, currentInboxId),
+        {
+          message: `Inbox ${currentInboxId} was not deleted`,
+          timeout: 30_000,
+        }
+      )
+      .toBe(false);
+  });
+
+  test('should complete full inbox creation flow with UI validation', async ({
+    page,
+  }) => {
+    const loginComponent = new Login(page);
+    await loginComponent.navigate();
+    await loginComponent.login(TEST_EMAIL, TEST_PASSWORD);
+    await page.waitForURL(/\/app\/accounts\/\d+\/dashboard/);
+
+    accountId = Number(page.url().match(/\/app\/accounts\/(\d+)\//)![1]);
+    const settingsInboxPage = new SettingsInboxPage(page);
+    await settingsInboxPage.navigate(accountId);
+
+    await expect(settingsInboxPage.getPageHeading()).toBeVisible();
+    await expect(settingsInboxPage.getAddInboxButton()).toBeVisible();
+
+    await settingsInboxPage.clickAddInboxButton();
+    await page.waitForURL(/\/settings\/inboxes\/new/);
+
+    const channelSelector = new ChannelSelector(page);
+    await expect(channelSelector.getPageHeading()).toBeVisible();
+    await channelSelector.selectApiChannel();
+
+    page.on('response', async response => {
+      if (
+        response.url().includes('/api/v1/accounts/') &&
+        response.url().includes('/inboxes') &&
+        response.request().method() === 'POST' &&
+        response.status() === 200
+      ) {
+        try {
+          const responseData = await response.json();
+          if (responseData.id) {
+            inboxId = responseData.id;
+          }
+        } catch {
+          // ignore non-JSON responses
+        }
+      }
+    });
+
+    const apiChannelForm = new ApiChannelForm(page);
+    await apiChannelForm.fillChannelName(testInbox.name);
+    await apiChannelForm.fillWebhookUrl(testInbox.webhookUrl);
+    await apiChannelForm.submitForm();
+    await expect.poll(() => inboxId).toBeTruthy();
+
+    const addAgentsForm = new AddAgentsForm(page);
+    await expect(addAgentsForm.getPageHeading()).toBeVisible();
+    await addAgentsForm.addFirstAgent();
+
+    await page.waitForURL(/\/settings\/inboxes\/.*\/finish/);
+    const finishSetup = new FinishSetup(page);
+    await expect(finishSetup.getPageHeading()).toBeVisible();
+  });
+});