> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Your Integration

> How to test your Signa integration safely.

Signa does not currently provide a dedicated sandbox environment. For integration testing, we recommend creating a **separate test organization** in the [dashboard](https://app.signa.so) with its own API key. You can then scope that key's usage, limits, and billing independently from your production organization.

## Recommended Workflow

1. **Create a test organization** from the dashboard.
2. **Issue a dedicated API key** for that organization and store it in your CI provider's secrets manager (e.g. `SIGNA_TEST_API_KEY`).
3. **Point integration tests at `https://api.signa.so`** using the test key. All keys use the format `sig_{48 hex chars}`, there is no separate base URL.
4. **Keep production keys out of CI**. Treat every API key as a credential regardless of which organization it belongs to.

## Integration Test Examples

### Basic: Verify Authentication

```typescript TypeScript (Vitest) theme={null}
import { describe, it, expect } from 'vitest';

const API_KEY = process.env.SIGNA_TEST_API_KEY!;
const BASE_URL = 'https://api.signa.so/v1';

describe('Signa API Authentication', () => {
  it('should authenticate with a valid key', async () => {
    const response = await fetch(`${BASE_URL}/offices`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });

    expect(response.status).toBe(200);
    const body = await response.json();
    expect(body.object).toBe('list');
  });

  it('should reject an invalid key', async () => {
    const response = await fetch(`${BASE_URL}/offices`, {
      headers: { Authorization: 'Bearer sig_invalid_key' },
    });

    expect(response.status).toBe(401);
  });
});
```

### Search and Paginate

```typescript TypeScript (Vitest) theme={null}
import { Signa } from '@signa-so/sdk';
import { describe, it, expect } from 'vitest';

const signa = new Signa({ api_key: process.env.SIGNA_TEST_API_KEY! });

describe('Search and pagination', () => {
  it('should search and paginate through results', async () => {
    // First page
    const page1 = await signa.trademarks.search({ query: 'health', limit: 10 });

    expect(page1.data.length).toBe(10);
    expect(page1.has_more).toBe(true);

    // Second page (SignaList follows the cursor for you)
    const page2 = await page1.getNextPage();

    expect(page2.data.length).toBeGreaterThan(0);

    // Verify no duplicates across pages
    const page1Ids = new Set(page1.data.map((t) => t.id));
    const page2Ids = page2.data.map((t) => t.id);
    for (const id of page2Ids) {
      expect(page1Ids.has(id)).toBe(false);
    }
  });
});
```

### Batch Fetch with Not-Found Handling

```typescript TypeScript (Vitest) theme={null}
import { Signa } from '@signa-so/sdk';
import { describe, it, expect } from 'vitest';

const signa = new Signa({ api_key: process.env.SIGNA_TEST_API_KEY! });

describe('Batch operations', () => {
  it('should return found trademarks and list unmatched ids separately', async () => {
    const response = await signa.trademarks.batch({
      ids: ['tm_abc123', 'tm_nonexistent_id', 'tm_def456'],
    });

    // Found items come back as full trademark objects in data
    expect(response.data.map((tm) => tm.id)).toEqual(['tm_abc123', 'tm_def456']);

    // Ids that matched nothing are listed in not_found, not as error entries in data
    expect(response.not_found).toEqual(['tm_nonexistent_id']);
  });
});
```

***

## CI/CD Integration

### Environment Variables

Set these in your CI pipeline:

| Variable             | Value     | Description                        |
| -------------------- | --------- | ---------------------------------- |
| `SIGNA_TEST_API_KEY` | `sig_...` | API key for your test organization |

### GitHub Actions Example

```yaml theme={null}
name: Integration Tests
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npm run test:integration
        env:
          SIGNA_TEST_API_KEY: ${{ secrets.SIGNA_TEST_API_KEY }}
```

<Warning>
  Store API keys in your CI provider's secrets manager. Treat every key as a credential.
</Warning>