s2-unit-test

name	s2-unit-test
description	Guidelines for writing and maintaining unit tests in the S2 project. Use when modifying source code to ensure proper test coverage. Use when this capability is needed.
metadata	{"author":"antvis"}

S2 Unit Testing Guidelines

When to Use This Skill

Use this skill when you:

• Modify code under packages/*/src/
• Fix bugs (especially with issue numbers)
• Add new features or functions

By default, all code changes require corresponding unit tests.

Test File Location Strategy

Step 1: Find Existing Test Files

Search for __tests__ directories to find where tests for the modified file already exist:

packages/s2-core/__tests__/unit/      # Unit tests organized by module
packages/s2-core/__tests__/bugs/      # Bug regression tests with issue numbers
packages/s2-core/__tests__/spreadsheet/  # Integration-level spreadsheet tests
packages/s2-react/__tests__/          # React component tests
packages/s2-vue/__tests__/            # Vue component tests

Step 2: Choose the Right Location

Scenario	Location	File Naming
Modifying existing function	Add to existing test file for that function	N/A
Bug fix with issue number	packages/s2-core/__tests__/bugs/	issue-{number}-spec.ts
New utility function	packages/s2-core/__tests__/unit/utils/	{function-name}-spec.ts
New cell logic	packages/s2-core/__tests__/unit/cell/	{cell-type}-spec.ts
New interaction	packages/s2-core/__tests__/unit/interaction/	{interaction-name}-spec.ts

Prefer adding tests to existing files over creating new ones. Reuse existing helper functions and test utilities.

Critical Rules

✅ Good Practices

1. Import from src directory - Tests must exercise actual source code:

// Good: Import functions/classes from src
import { getCellWidth, getDisplayText } from '@/utils/text';
import { PivotSheet } from '@/sheet-type';

// Good: Use path aliases
import { createPivotSheet } from 'tests/util/helpers';

2. Test real behavior - Create actual instances and verify logic:

// Good: Create real S2 instance and test behavior
const s2 = createPivotSheet(options);
await s2.render();
expect(s2.facet.getColCells()[0].getMeta().width).toBe(expectedWidth);

3. Reproduce bugs with real code paths:

// Good: Bug reproduction that exercises src code
describe('issue #3212', () => {
  test('should keep column width after hiding value', async () => {
    const s2 = createPivotSheet({ style: { layoutWidthType: 'compact' } });
    await s2.render();
    
    const originalWidth = s2.facet.getColCells()[0].getMeta().width;
    s2.setOptions({ style: { colCell: { hideValue: true } } });
    await s2.render();
    
    expect(s2.facet.getColCells()[0].getMeta().width).toBe(originalWidth);
  });
});

❌ Bad Practices

1. Never reimplement logic in tests:

// BAD: Reimplementing the logic defeats the purpose
function myLocalCalculation(a, b) {
  return a + b; // This is useless! If src is broken, test still passes
}
expect(myLocalCalculation(1, 2)).toBe(3);

2. Never import only types:

// BAD: Only importing types doesn't test any actual code
import type { S2Options, SpreadSheet } from '@/common';
// No actual code is being tested!

3. Never test mocked implementations instead of real code:

// BAD: Testing your own mock, not the actual source
const mockFn = jest.fn().mockReturnValue(42);
expect(mockFn()).toBe(42); // This tests nothing useful

Test Structure Template

/**
 * @description spec for issue #XXXX (if applicable)
 * https://github.com/antvis/S2/issues/XXXX
 */
import { SomeFunction, SomeClass } from '@/path/to/src';
import { createPivotSheet } from 'tests/util/helpers';

describe('FeatureName', () => {
  test('should do expected behavior', () => {
    // Arrange
    const input = { /* ... */ };
    
    // Act
    const result = SomeFunction(input);
    
    // Assert
    expect(result).toEqual(expectedOutput);
  });
});

Running Tests

# Run all tests for a package
pnpm --filter @antv/s2 test

# Run specific test file
pnpm --filter @antv/s2 test -- --testPathPattern="issue-3212"

# Run with coverage
pnpm --filter @antv/s2 test:coverage

Goal

The primary goal of unit tests is to:

• Increase line coverage - Every line of src code should be exercised
• Increase branch coverage - Test all conditional paths
• Prevent regressions - Ensure bugs don't reappear

Tests that don't import and exercise actual src code provide no coverage benefit.

---

Source: antvis/S2 — distributed by TomeVault.