fix(kyc): tell the user a recommendation request awaits confirmation

e2e-stack/specs/kyc.spec.ts

@@ -252,6 +252,21 @@ test.describe('KYC area e2e', () => {
     expect(new URL(page.url()).pathname).toMatch(/login/);
   });
 
+  test('/kyc?step=Recommendation shows the pending confirmation hint', async ({ page }) => {
+    const user = await createUser({ tag: 'kyc-rec-pending', kycLevel: 10, language: 'EN' });
+    await createKycStep(user.userDataId, { name: 'Recommendation', status: 'InternalReview' });
+
+    await gotoWithSession(page, '/kyc?step=Recommendation', user.jwt);
+
+    await expect(
+      page.getByText(
+        'Your recommendation request has been sent. Your contact person has to confirm it before you can continue.',
+      ),
+    ).toBeVisible({ timeout: 20000 });
+    await expect(page.getByText('This step has already been finished.')).toHaveCount(0);
+    await expect(page.getByRole('button', { name: 'Continue' })).toBeVisible();
+  });
+
   // ---------------------------------------------------------------------------
   // /kyc/redirect - do NOT use openScreen (immediate navigate to /kyc)
   // ---------------------------------------------------------------------------

e2e/kyc-screen.spec.ts

@@ -0,0 +1,103 @@
+import { expect, Page, Route, test } from '@playwright/test';
+
+/**
+ * Visual baselines for the KYC step-result panel.
+ * Handbook group key: kyc-screen (from this file name before `.spec.ts-`).
+ */
+
+const PENDING =
+  /Your recommendation request has been sent|Deine Empfehlungsanfrage wurde verschickt/;
+const FINISHED = /This step has already been finished|Dieser Schritt ist bereits abgeschlossen/;
+const FAILED = /This step has failed|Dieser Schritt ist fehlgeschlagen/;
+
+function session(currentStep: {
+  name: string;
+  status: string;
+  reason?: string;
+  sequenceNumber?: number;
+}) {
+  return {
+    kycLevel: 10,
+    tradingLimit: { limit: 1000, period: 'Day' },
+    language: { symbol: 'EN', name: 'English' },
+    kycClients: [],
+    kycSteps: [
+      {
+        name: currentStep.name,
+        status: currentStep.status,
+        sequenceNumber: currentStep.sequenceNumber ?? 0,
+        isCurrent: true,
+        reason: currentStep.reason,
+      },
+    ],
+    currentStep: {
+      name: currentStep.name,
+      status: currentStep.status,
+      sequenceNumber: currentStep.sequenceNumber ?? 0,
+      reason: currentStep.reason,
+    },
+  };
+}
+
+async function mockKyc(
+  page: Page,
+  body: ReturnType<typeof session>,
+): Promise<void> {
+  await page.route(/\/v2\/kyc(?:\/[^?]*)?(?:\?|$)/, async (route: Route) => {
+    if (route.request().method() !== 'GET') {
+      await route.continue();
+      return;
+    }
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify(body),
+    });
+  });
+}
+
+test.describe('KYC step result', () => {
+  test('recommendation InReview: pending confirmation hint', async ({ page }) => {
+    await mockKyc(page, session({ name: 'Recommendation', status: 'InReview' }));
+
+    await page.goto('/kyc?code=e2e-rec&step=Recommendation');
+
+    await expect(page.getByText(PENDING)).toBeVisible({ timeout: 20000 });
+    await expect(page.getByText(FINISHED)).toHaveCount(0);
+    await expect(page.getByText(FAILED)).toHaveCount(0);
+
+    await expect(page).toHaveScreenshot('kyc-recommendation-pending.png', {
+      maxDiffPixels: 10000,
+    });
+  });
+
+  test('ident InReview: finished copy', async ({ page }) => {
+    await mockKyc(page, session({ name: 'Ident', status: 'InReview' }));
+
+    await page.goto('/kyc?code=e2e-ident&step=Ident');
+
+    await expect(page.getByText(FINISHED)).toBeVisible({ timeout: 15000 });
+    await expect(page.getByText(PENDING)).toHaveCount(0);
+
+    await expect(page).toHaveScreenshot('kyc-step-finished.png', {
+      maxDiffPixels: 10000,
+    });
+  });
+
+  test('recommendation Failed: failed copy and reason', async ({ page }) => {
+    await mockKyc(
+      page,
+      session({ name: 'Recommendation', status: 'Failed', reason: 'AccountExists' }),
+    );
+
+    await page.goto('/kyc?code=e2e-fail&step=Recommendation');
+
+    await expect(page.getByText(FAILED)).toBeVisible({ timeout: 15000 });
+    await expect(page.getByText('AccountExists')).toBeVisible();
+    await expect(page.getByText(PENDING)).toHaveCount(0);
+
+    await expect(page).toHaveScreenshot('kyc-step-failed.png', {
+      maxDiffPixels: 10000,
+    });
+  });
+});

scripts/handbook/metadata.json

@@ -123,6 +123,10 @@
     "title": "Swap Lightning (URL-Parameter)",
     "description": "Swap-Flow mit Lightning-URL-Parameter."
   },
+  "kyc-screen": {
+    "title": "KYC (Nutzer)",
+    "description": "KYC-Schritt-Ergebnis: Empfehlung wartet auf Bestätigung der Ansprechperson; abgeschlossener Schritt; fehlgeschlagener Schritt."
+  },
   "login-process": {
     "title": "Login-Prozess",
     "description": "Login und Home-Seite nach Authentifizierung."

src/__tests__/kyc-step-result-hint.test.tsx

@@ -0,0 +1,87 @@
+import { render, screen } from '@testing-library/react';
+import { KycStepBase, KycStepName, KycStepReason, KycStepStatus } from '@dfx.swiss/react';
+
+jest.mock('@dfx.swiss/react', () => ({
+  KycStepName: {
+    RECOMMENDATION: 'Recommendation',
+    IDENT: 'Ident',
+  },
+  KycStepStatus: {
+    IN_REVIEW: 'InReview',
+    COMPLETED: 'Completed',
+    FAILED: 'Failed',
+  },
+  KycStepReason: {
+    ACCOUNT_EXISTS: 'AccountExists',
+  },
+}));
+
+jest.mock('../contexts/settings.context', () => ({
+  useSettingsContext: () => ({
+    translate: (_scope: string, key: string) => key,
+  }),
+}));
+
+import { KycStepResultHint } from '../components/kyc-step-result-hint';
+
+const PENDING =
+  'Your recommendation request has been sent. Your contact person has to confirm it before you can continue.';
+const FINISHED = 'This step has already been finished.';
+const FAILED = 'This step has failed.';
+
+function step(partial: Pick<KycStepBase, 'name' | 'status'> & Partial<KycStepBase>): KycStepBase {
+  return {
+    sequenceNumber: 1,
+    ...partial,
+  };
+}
+
+describe('KycStepResultHint', () => {
+  it('shows the pending recommendation text when Recommendation is InReview', () => {
+    render(<KycStepResultHint step={step({ name: KycStepName.RECOMMENDATION, status: KycStepStatus.IN_REVIEW })} />);
+
+    expect(screen.getByText(PENDING)).toBeInTheDocument();
+    expect(screen.queryByText(FINISHED)).toBeNull();
+    expect(screen.queryByText(FAILED)).toBeNull();
+  });
+
+  it('shows the finished text when Recommendation is Completed', () => {
+    render(<KycStepResultHint step={step({ name: KycStepName.RECOMMENDATION, status: KycStepStatus.COMPLETED })} />);
+
+    expect(screen.getByText(FINISHED)).toBeInTheDocument();
+    expect(screen.queryByText(PENDING)).toBeNull();
+    expect(screen.queryByText(FAILED)).toBeNull();
+  });
+
+  it('shows the finished text when Ident is InReview', () => {
+    render(<KycStepResultHint step={step({ name: KycStepName.IDENT, status: KycStepStatus.IN_REVIEW })} />);
+
+    expect(screen.getByText(FINISHED)).toBeInTheDocument();
+    expect(screen.queryByText(PENDING)).toBeNull();
+    expect(screen.queryByText(FAILED)).toBeNull();
+  });
+
+  it('shows the failed text without a reason when none is set', () => {
+    render(<KycStepResultHint step={step({ name: KycStepName.RECOMMENDATION, status: KycStepStatus.FAILED })} />);
+
+    expect(screen.getByText(FAILED)).toBeInTheDocument();
+    expect(screen.queryByText(KycStepReason.ACCOUNT_EXISTS)).toBeNull();
+  });
+
+  it('shows the failed text and reason when Recommendation is Failed', () => {
+    render(
+      <KycStepResultHint
+        step={step({
+          name: KycStepName.RECOMMENDATION,
+          status: KycStepStatus.FAILED,
+          reason: KycStepReason.ACCOUNT_EXISTS,
+        })}
+      />,
+    );
+
+    expect(screen.getByText(FAILED)).toBeInTheDocument();
+    expect(screen.getByText(KycStepReason.ACCOUNT_EXISTS)).toBeInTheDocument();
+    expect(screen.queryByText(PENDING)).toBeNull();
+    expect(screen.queryByText(FINISHED)).toBeNull();
+  });
+});