ci

Author: zbeyens

.cursor/rules/unit-testing.mdc

@@ -0,0 +1,397 @@
+---
+description: Guidelines for writing unit tests in the Plate monorepo using Jest, React Testing Library, and Slate Hyperscript JSX.
+globs: packages/**/*.spec.{ts,tsx}, packages/**/*.test.{ts,tsx}
+alwaysApply: true
+---
+
+- **Testing Framework and Setup:**
+  - Use Jest with TypeScript (`ts-jest`) and SWC transformer
+  - Tests run in `jsdom` environment
+  - Test files must end with `.spec.ts` or `.spec.tsx`
+  - Global setup includes `@testing-library/jest-dom` and Slate test utils
+  - Use `describe` blocks to group related tests
+  - Use `it` or `test` for individual test cases
+  - Use `beforeEach` for common setup between tests
+  - E2E tests use Playwright (see `tooling/e2e/*.spec.ts`)
+
+- **Required Imports for Slate Hyperscript JSX:**
+  ```typescript
+  /** @jsx jsx */
+  import { jsx } from '@platejs/test-utils';
+
+  jsx; // Required to prevent removal by compiler
+  ```
+  
+  Or for typed JSX in docx tests:
+  ```typescript
+  /** @jsx jsxt */
+  import { jsxt } from '@platejs/test-utils';
+
+  jsxt; // Required to prevent removal by compiler
+  ```
+
+- **Editor Creation Patterns:**
+  ```typescript
+  // ✅ DO: Use createPlateEditor for React components
+  import { createPlateEditor } from '@platejs/core/react';
+  
+  const editor = createPlateEditor({
+    plugins: [MyPlugin],
+  });
+
+  // ✅ DO: Use createEditor for pure Slate operations
+  import { createEditor } from '@platejs/slate';
+  
+  const editor = createEditor();
+  editor.children = initialValue;
+  ```
+
+- **Slate Hyperscript JSX Elements:**
+  - Common elements: `<editor>`, `<hp>`, `<htext>`, `<hh1>` through `<hh6>`
+  - List elements: `<hul>`, `<hol>`, `<hli>`
+  - Table elements: `<htable>`, `<htr>`, `<htd>`, `<hth>`
+  - Inline elements: `<ha>`, `<htext bold>`, `<htext italic>`
+  - Special elements: `<hcodeblock>`, `<hblockquote>`, `<hmention>`
+  
+  ```typescript
+  // ✅ DO: Use hyperscript JSX for test data
+  const input = (
+    <editor>
+      <hp>
+        <htext>Hello </htext>
+        <htext bold>world</htext>
+      </hp>
+    </editor>
+  );
+  ```
+
+- **Plugin Testing Patterns:**
+  ```typescript
+  // ✅ DO: Test plugin configuration
+  const TestPlugin = createSlatePlugin({
+    key: 'test',
+    options: { testOption: 'value' },
+  }).extendEditorApi(() => ({
+    testMethod: () => 'result',
+  }));
+
+  const editor = createPlateEditor({
+    plugins: [TestPlugin],
+  });
+
+  // Test API methods
+  expect(editor.api.testMethod()).toBe('result');
+  
+  // Test plugin retrieval
+  const plugin = editor.getPlugin(TestPlugin);
+  expect(plugin.options.testOption).toBe('value');
+  ```
+
+- **Transform Testing:**
+  ```typescript
+  // ✅ DO: Test transforms with clear initial and expected values
+  describe('wrapNodes', () => {
+    it('should wrap the node', () => {
+      const initialValue = [
+        {
+          children: [{ text: 'test' }],
+          type: 'paragraph',
+        },
+      ];
+
+      const expectedValue = [
+        {
+          children: [
+            {
+              children: [{ text: 'test' }],
+              type: 'blockquote',
+            },
+          ],
+          type: 'paragraph',
+        },
+      ];
+
+      const editor = createEditor();
+      editor.children = initialValue;
+
+      editor.tf.wrapNodes(
+        { children: [], type: 'blockquote' },
+        { at: [0, 0] }
+      );
+
+      expect(editor.children).toEqual(expectedValue);
+    });
+  });
+  ```
+
+- **Utility Function Testing:**
+  ```typescript
+  // ✅ DO: Test pure functions with multiple scenarios
+  describe('isImageUrl', () => {
+    it('should return true for image URLs', () => {
+      expect(isImageUrl('https://example.com/image.jpg')).toBe(true);
+      expect(isImageUrl('https://example.com/image.png')).toBe(true);
+    });
+
+    it('should return false for non-image URLs', () => {
+      expect(isImageUrl('https://example.com/file.pdf')).toBe(false);
+      expect(isImageUrl('not-a-url')).toBe(false);
+    });
+  });
+  ```
+
+- **Async Testing:**
+  ```typescript
+  // ✅ DO: Use async/await for asynchronous tests
+  it('should handle async operations', async () => {
+    const result = await someAsyncFunction();
+    expect(result).toBeDefined();
+  });
+  ```
+
+- **Mock Usage:**
+  ```typescript
+  // ✅ DO: Mock external dependencies
+  jest.mock('nanoid', () => ({
+    nanoid: () => 'mock-id',
+  }));
+
+  // ✅ DO: Spy on console methods in setup
+  jest.spyOn(global.console, 'warn').mockImplementation(() => jest.fn());
+  
+  // ✅ DO: Mock specific functions
+  const mockOnChange = jest.fn();
+  const mockOnKeyDown = jest.fn();
+  
+  // ✅ DO: Mock complex objects
+  jest.spyOn(JSON, 'parse').mockReturnValue(<fragment>mocked</fragment>);
+  ```
+
+- **Test Organization:**
+  ```typescript
+  // ✅ DO: Group related tests logically
+  describe('FeatureName', () => {
+    describe('when condition A', () => {
+      it('should behavior X', () => {
+        // test
+      });
+    });
+
+    describe('when condition B', () => {
+      it('should behavior Y', () => {
+        // test
+      });
+    });
+  });
+  ```
+
+- **Common Test Patterns:**
+  - Test both positive and negative cases
+  - Test edge cases and boundary conditions
+  - Keep tests focused on a single behavior
+  - Use descriptive test names that explain the expected behavior
+  - Avoid testing implementation details
+  - Test the public API, not internal functions
+
+- **React Component Testing:**
+  ```typescript
+  // ✅ DO: Use React Testing Library for components
+  import { render } from '@testing-library/react';
+  
+  it('should render component', () => {
+    const { getByText } = render(<MyComponent />);
+    expect(getByText('Expected Text')).toBeInTheDocument();
+  });
+  ```
+
+- **Type Testing:**
+  ```typescript
+  // ✅ DO: Test TypeScript types when relevant
+  it('should have correct types', () => {
+    let a: SlatePluginContext<Config> = {} as any;
+    const b = getEditorPlugin(editor, plugin);
+    a = b; // Should compile without errors
+    expect(a).toBeDefined();
+  });
+  ```
+
+- **DataTransfer Testing:**
+  ```typescript
+  // ✅ DO: Create DataTransfer for paste/drop testing
+  import { createDataTransfer } from '@platejs/test-utils';
+  
+  const dataTransfer = createDataTransfer(new Map([
+    ['text/html', '<p>Hello</p>'],
+    ['text/plain', 'Hello']
+  ]));
+  
+  // Or inline:
+  const dataTransfer = {
+    constructor: { name: 'DataTransfer' },
+    getData: (format: string) => 
+      format === 'text/html' && '<p>Hello</p>',
+  } as any;
+  
+  editor.tf.insertData(dataTransfer);
+  ```
+
+- **Fragment and Selection Testing:**
+  ```typescript
+  // ✅ DO: Use cursor and selection markers in JSX
+  const input = (
+    <editor>
+      <hp>
+        test<cursor />
+      </hp>
+    </editor>
+  ) as any as SlateEditor;
+  
+  const editor = createPlateEditor({
+    selection: input.selection,
+    value: input.children,
+  });
+  ```
+
+- **Plugin Configuration Testing:**
+  ```typescript
+  // ✅ DO: Test plugin configuration and extension
+  const TestPlugin = BasePlugin.configure({
+    options: { newOption: 'value' },
+  }).extendEditorApi(() => ({
+    newMethod: () => 'result',
+  }));
+  
+  // Test plugin resolution
+  const editor = createPlateEditor({ plugins: [TestPlugin] });
+  const resolvedPlugin = editor.plugins.test;
+  expect(resolvedPlugin.options.newOption).toBe('value');
+  ```
+
+- **Store and Hook Testing:**
+  ```typescript
+  // ✅ DO: Use renderHook for testing hooks
+  import { renderHook } from '@testing-library/react';
+  
+  const wrapper = ({ children }: any) => (
+    <PlateController {...props}>{children}</PlateController>
+  );
+  
+  const { result } = renderHook(() => useMyHook(), { wrapper });
+  expect(result.current).toBe(expectedValue);
+  ```
+
+- **Snapshot Testing:**
+  ```typescript
+  // ✅ DO: Use snapshots for serialization tests
+  const result = serializeMd(editor, { value: slateNodes });
+  expect(result).toMatchSnapshot();
+  ```
+
+- **Editor Transform Testing:**
+  ```typescript
+  // ✅ DO: Test editor transforms thoroughly
+  editor.tf.insertText('Hello');
+  editor.tf.delete({ distance: 5, reverse: true });
+  editor.tf.wrapNodes({ type: 'blockquote' }, { at: [0, 0] });
+  editor.tf.insertFragment([{ type: 'p', children: [{ text: 'new' }] }]);
+  ```
+
+- **Error Testing:**
+  ```typescript
+  // ✅ DO: Test error conditions
+  expect(() => {
+    editor.api.debug.error('Test error', 'TEST_ERROR');
+  }).toThrow(PlateError);
+  
+  try {
+    someFunction();
+  } catch (error) {
+    expect(error).toBeInstanceOf(CustomError);
+    expect((error as CustomError).message).toBe('Expected message');
+  }
+  ```
+
+- **Logger and Debug Testing:**
+  ```typescript
+  // ✅ DO: Mock loggers for debug testing
+  const mockLogger = jest.fn();
+  const editor = createPlateEditor({
+    plugins: [
+      DebugPlugin.configure({
+        options: { logger: { log: mockLogger } as any },
+      }),
+    ],
+  });
+  
+  editor.api.debug.log('Test message');
+  expect(mockLogger).toHaveBeenCalledWith('Test message', expect.any(String));
+  ```
+
+- **HTML Deserialization Testing:**
+  ```typescript
+  // ✅ DO: Test HTML deserialization
+  import { getHtmlDocument } from '@platejs/test-utils';
+  
+  const html = '<div>test</div>';
+  const element = getHtmlDocument(html).body;
+  
+  const result = deserializeHtml(editor, { element });
+  expect(result).toEqual(expectedOutput);
+  ```
+
+- **Multiple Test Scenarios:**
+  ```typescript
+  // ✅ DO: Use describe blocks for different scenarios
+  describe('when condition is true', () => {
+    it('should behave one way', () => {});
+  });
+  
+  describe('when condition is false', () => {
+    it('should behave another way', () => {});
+  });
+  ```
+
+- **Type Testing with Generics:**
+  ```typescript
+  // ✅ DO: Test generic type constraints
+  type Config = PluginConfig<'test', { option: string }>;
+  const plugin = createTSlatePlugin<Config>({ key: 'test' });
+  
+  // Should compile without errors
+  const typed: SlatePluginContext<Config> = getEditorPlugin(editor, plugin);
+  ```
+
+- **Test Utilities:**
+  - Use `createTestEditor()` for tests requiring a configured editor
+  - Use `createPlateTestEditor()` for async testing with test harness
+  - Use `resolvePluginTest()` for testing plugin resolution
+  - Use `@testing-library/jest-dom` matchers like `toBeInTheDocument()`
+  - Mock `nanoid` for consistent IDs in tests
+  - `createDataTransfer()` for DataTransfer mocking
+  - `getHtmlDocument()` for HTML parsing in tests
+
+- **Common Patterns to Avoid:**
+  ```typescript
+  // ❌ DON'T: Use relative imports in tests
+  import { myFunction } from '../src/myFunction';
+  
+  // ✅ DO: Use package imports
+  import { myFunction } from '@platejs/package-name';
+  
+  // ❌ DON'T: Test implementation details
+  expect(privateFunction).toHaveBeenCalled();
+  
+  // ✅ DO: Test public API behavior
+  expect(editor.api.publicMethod()).toBe(expectedResult);
+  ```
+
+- **Testing Best Practices Summary:**
+  - Write tests that read like documentation
+  - Focus on behavior, not implementation
+  - Use descriptive test names: "should [expected behavior] when [condition]"
+  - Keep tests isolated and independent
+  - Mock external dependencies, not internal functions
+  - Use the simplest approach that properly tests the feature
+  - Refer to existing tests in the same package for patterns
+
+Follow existing test patterns in the codebase and maintain consistency with the testing conventions.