diff_docs_test.diff

diff --git a/admin/src/pages/__tests__/Docs.test.tsx b/admin/src/pages/__tests__/Docs.test.tsx
new file mode 100644
index 00000000..8371126d
--- /dev/null
+++ b/admin/src/pages/__tests__/Docs.test.tsx
@@ -0,0 +1,230 @@
+import React from 'react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter } from 'react-router-dom';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import Docs from '../Docs';
+import { getDocs, runValidation } from '@/lib/api';
+import type { ValidationResultDto } from '@/lib/types';
+
+vi.mock('@/lib/api');
+vi.mock('@/components/ui/LoadingSpinner', () => ({
+  LoadingSpinner: ({ size }: { size?: string }) => (
+    <div data-testid={`spinner-${size ?? 'md'}`} role="status">
+      Loading
+    </div>
+  ),
+}));
+
+const mockGetDocs = vi.mocked(getDocs);
+const mockRunValidation = vi.mocked(runValidation);
+
+const mockDocsContent = `# API Documentation
+
+This is the ICC Rule Engine API documentation.
+
+## Getting Started
+
+Welcome to the ICC Rule Engine API.`;
+
+const validationPass: ValidationResultDto = {
+  id: 'validation-123',
+  status: 'pass',
+  errors: [],
+};
+
+const validationFail: ValidationResultDto = {
+  id: 'validation-456',
+  status: 'fail',
+  errors: ['Document date is missing', 'Amount exceeds maximum allowed value'],
+};
+
+const renderDocs = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+    },
+  });
+
+  const user = userEvent.setup();
+
+  render(
+    <QueryClientProvider client={queryClient}>
+      <MemoryRouter>
+        <Docs />
+      </MemoryRouter>
+    </QueryClientProvider>
+  );
+
+  return { user };
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockGetDocs.mockResolvedValue(mockDocsContent);
+  mockRunValidation.mockResolvedValue(validationPass);
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('Docs page', () => {
+  describe('documentation tab', () => {
+    it('renders hero copy and markdown content', async () => {
+      renderDocs();
+
+      expect(screen.getByText('Documentation & Playground')).toBeInTheDocument();
+      expect(
+        screen.getByText(
+          'Explore the API documentation and test validation rules with the interactive playground.'
+        )
+      ).toBeInTheDocument();
+
+      await waitFor(() => {
+        expect(screen.getByRole('heading', { level: 3, name: 'API Documentation' })).toBeInTheDocument();
+        expect(screen.getByText('Getting Started')).toBeInTheDocument();
+      });
+    });
+
+    it('shows loading indicator while docs are fetched', () => {
+      mockGetDocs.mockImplementation(() => new Promise<string>(() => {}));
+
+      renderDocs();
+
+      expect(screen.getByTestId('docs-loading')).toBeInTheDocument();
+    });
+
+    it('shows error alert when docs fetch fails', async () => {
+      mockGetDocs.mockRejectedValue(new Error('Service unavailable'));
+
+      renderDocs();
+
+      const errorMessage = await screen.findByText('Service unavailable', undefined, { timeout: 3000 });
+      expect(errorMessage).toBeInTheDocument();
+      expect(screen.getByText('Failed to load documentation')).toBeInTheDocument();
+    });
+
+    it('shows empty state when documentation content is missing', async () => {
+      mockGetDocs.mockResolvedValue('   ');
+
+      renderDocs();
+
+      await waitFor(() => {
+        expect(screen.getByText('Documentation unavailable')).toBeInTheDocument();
+        expect(
+          screen.getByText('The documentation content is not available right now. Please check back soon.')
+        ).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe('playground interactions', () => {
+    const openPlaygroundTab = async (user: ReturnType<typeof userEvent.setup>) => {
+      await user.click(screen.getByRole('button', { name: /interactive playground/i }));
+    };
+
+    it('validates payload successfully and displays pass badge', async () => {
+      const { user } = renderDocs();
+
+      await openPlaygroundTab(user);
+      await user.click(screen.getByTestId('run-validation'));
+
+      await waitFor(() => {
+        expect(screen.getByTestId('validation-result')).toBeInTheDocument();
+        expect(screen.getByText('Pass')).toBeInTheDocument();
+        expect(screen.getByText('validation-123')).toBeInTheDocument();
+      });
+
+      const [payload] = mockRunValidation.mock.calls.at(-1) ?? [];
+      expect(payload).toMatchObject({
+        document: expect.any(Object),
+      });
+    });
+
+    it('shows validation errors when payload fails', async () => {
+      mockRunValidation.mockResolvedValueOnce(validationFail);
+      const { user } = renderDocs();
+
+      await openPlaygroundTab(user);
+      await user.click(screen.getByTestId('run-validation'));
+
+      await waitFor(() => {
+        expect(screen.getByText('Fail')).toBeInTheDocument();
+        expect(screen.getByText('Errors (2)')).toBeInTheDocument();
+        expect(screen.getByText('Document date is missing')).toBeInTheDocument();
+      });
+    });
+
+    it('shows mutation loading indicator during validation', async () => {
+      mockRunValidation.mockImplementation(() => new Promise<ValidationResultDto>(() => {}));
+      const { user } = renderDocs();
+
+      await openPlaygroundTab(user);
+      await user.click(screen.getByTestId('run-validation'));
+
+      await waitFor(() => {
+        expect(screen.getByTestId('validation-loading')).toBeInTheDocument();
+        expect(screen.getByText('Running validation...')).toBeInTheDocument();
+      });
+    });
+
+    it('displays API error responses from validation', async () => {
+      mockRunValidation.mockRejectedValueOnce(new Error('Network error'));
+      const { user } = renderDocs();
+
+      await openPlaygroundTab(user);
+      await user.click(screen.getByTestId('run-validation'));
+
+      await waitFor(() => {
+        expect(screen.getByTestId('validation-api-error')).toBeInTheDocument();
+        expect(screen.getByText('Validation failed: Network error')).toBeInTheDocument();
+      });
+    });
+
+    it('shows syntax error when payload is invalid JSON', async () => {
+      const { user } = renderDocs();
+
+      await openPlaygroundTab(user);
+      const textarea = screen.getByPlaceholderText('Enter your JSON payload here...');
+      await user.clear(textarea);
+      fireEvent.change(textarea, { target: { value: '{"invalid": json}' } });
+      await user.click(screen.getByTestId('run-validation'));
+
+      await waitFor(() => {
+        expect(screen.getByTestId('validation-syntax-error')).toBeInTheDocument();
+        expect(screen.getByText('Invalid JSON format. Please check your payload syntax.')).toBeInTheDocument();
+      });
+    });
+
+    it('shows error when payload is empty', async () => {
+      const { user } = renderDocs();
+
+      await openPlaygroundTab(user);
+      const textarea = screen.getByPlaceholderText('Enter your JSON payload here...');
+      await user.clear(textarea);
+      await user.click(screen.getByTestId('run-validation'));
+
+      await waitFor(() => {
+        expect(screen.getByText('Payload cannot be empty.')).toBeInTheDocument();
+      });
+    });
+
+    it('formats JSON payload and resets sample content', async () => {
+      const { user } = renderDocs();
+
+      await openPlaygroundTab(user);
+      const textarea = screen.getByPlaceholderText('Enter your JSON payload here...');
+      await user.clear(textarea);
+      fireEvent.change(textarea, { target: { value: '{"test":"value"}' } });
+
+      await user.click(screen.getByRole('button', { name: /format json/i }));
+      expect(textarea).toHaveValue('{\n  "test": "value"\n}');
+
+      fireEvent.change(textarea, { target: { value: '{"changed":true}' } });
+      await user.click(screen.getByRole('button', { name: /reset/i }));
+      expect(textarea.value).toContain('creditType');
+    });
+  });
+});