testing-clickup-cli

Test Suite Overview

Unit tests run in CI. E2E tests require CLICKUPAPITOKEN in .env.test and are not part of CI.

Running Tests

npm test                          # all unit tests
npm test -- tests/unit/commands/  # just command tests
npm test -- -t "sprint"           # filter by test name
npm run test:e2e                  # e2e tests (needs .env.test)

The unit test global setup runs npm run build before tests start.

E2E Test Workspace

Tests run against the personal ClickUp workspace (profile: personal).

Space: E2E Tests (90166622768)

Pre-populated with test fixtures:

Space: ClickUp CLI (90166622769)

Project tracking space. Not used for tests - used for tracking releases and features.

E2E Test Patterns

Lifecycle tests (tests/e2e/lifecycle.e2e.ts)

These create test data, verify operations, and clean up:

Each suite uses beforeAll to find the Backlog list and afterAll to clean up created tasks.

API tests (tests/e2e/api.e2e.ts)

Tests API client methods directly: getSpaces, getLists, getTask, sprint detection.

Unit Test Patterns

Mocking ClickUpClient

Every command test mocks the API client with vi.mock:

const mockGetTask = vi.fn().mockResolvedValue({ id: 't1', name: 'Task' })

vi.mock('../../../src/api.js', () => ({
  ClickUpClient: vi.fn().mockImplementation(function () {
    return { getTask: mockGetTask }
  }),
}))

The function keyword (not arrow) is required for Vitest 4's new semantics.

Testing command functions

Commands export pure functions. Tests import and call them directly:

const { updateTask } = await import('../../../src/commands/update.js')
await updateTask({ apiToken: 'pk_t', teamId: 'team1' }, 't1', { status: 'done' })
expect(mockUpdateTask).toHaveBeenCalledWith('t1', { status: 'done' })

Metadata sync test

tests/unit/commands/completion.test.ts verifies that:

1. Every command registered in Commander is listed in src/commands/metadata.ts
2. The docs/commands.md quick reference section matches what metadata generates

If you add a new command, you MUST add it to metadata.ts. If you add new flags, add them too. Then run node --import tsx scripts/sync-command-docs.ts to regenerate the docs.

Adding New Tests

New unit test

1. Create tests/unit/commands/<name>.test.ts
2. Mock ClickUpClient with the methods your command uses
3. Test happy path, error cases, edge cases
4. Run npm test -- tests/unit/commands/<name>.test.ts

New e2e test

1. Add to tests/e2e/lifecycle.e2e.ts or create a new *.e2e.ts file
2. Use the Backlog list in E2E Tests space for creating test data
3. Always clean up: delete created tasks/checklists in afterAll
4. Use describe.skipIf(!TOKEN) to skip when no API token is set
5. Run npm run test:e2e

Config for E2E

# .env.test (gitignored)
CLICKUP_API_TOKEN=pk_...   # personal workspace token

Copy from .env.test.example and fill in your token.