# Testing

> Required conventions for writing and modifying tests — framework, file template, section ordering, and security test requirements. TRIGGER when: creating or modifying any file under test/; adding, changing, or removing tool parameters or response behavior that requires test updates; user asks about testing patterns or test structure.

- Skill: `pingidentity/testing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pingidentity/testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pingidentity/testing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: pingidentity (https://skillmd.com/u/pingidentity)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pingidentity/testing

---


# Testing

**Framework**: Vitest + MSW (Mock Service Worker). Tests mirror source structure under `test/tools/<category>/`.

**Core principle**: Test our application logic (request construction, response processing, input validation, error handling), not the API itself.

## Test File Template

```typescript
import { describe, it, expect } from 'vitest';
import { myNewToolTool } from '../../../src/tools/category/myNewTool.js';
import { snapshotTest } from '../../helpers/snapshotTest.js';
import { setupTestEnvironment } from '../../helpers/testEnvironment.js';
import { server } from '../../setup.js';
import { http, HttpResponse } from 'msw';

describe('myNewTool', () => {
  const getSpy = setupTestEnvironment(); // Sets AIC_BASE_URL, spies on makeAuthenticatedRequest

  // 1. Snapshot test (required for every tool)
  it('should match tool schema snapshot', async () => {
    await snapshotTest('myNewTool', myNewToolTool);
  });

  // 2. Request construction — verify URL, scopes, method, body via spy
  describe('Request Construction', () => {
    it('constructs correct URL', async () => {
      await myNewToolTool.toolFunction({ param1: 'value' });
      const [url, scopes, options] = getSpy().mock.calls.at(-1)!;
      expect(url).toBe('https://test.forgeblocks.com/your/api/endpoint');
      expect(scopes).toEqual(['fr:idm:*']);
    });
  });

  // 3. Response handling — use server.use() to provide MSW responses
  // 4. Input validation — test Zod schemas directly
  // 5. Error handling — override handlers with error responses
});
```

## Section Ordering

1. Snapshot Test
2. Request Construction
3. Response Handling
4. Input Validation
5. Error Handling

Complex orchestration tools add "Application Logic" after snapshot tests.

## Security Tests

Always include for tools that accept user input:

- Path traversal prevention for ID parameters (`schema.parse('../etc/passwd')` should throw)
- Query injection prevention for user-provided filter strings

## After Adding a Tool

Run `npm run test:snapshots:update` to create its snapshot, then `npm test` to verify.