Test Mode

Test your integration without hitting the NotPixel API. Perfect for development, testing, and CI/CD pipelines.

Enable Test Mode


import Ads from 'notpixel';
 
const ads = new Ads({ mock: true });
 
const ad = await ads.getAd({ input: 'any query' });
// Returns a mock ad without API call

Via Environment Variable


NOTPIXEL_MOCK=1


// Test Mode is automatically enabled
const ads = new Ads({ publisherId: 'pub-xxx' });

Reproducible Results

Use a seed for consistent mock ads across runs:


const ads = new Ads({
  mock: { seed: 42 },
});
 
// Same seed = same mock ads every time
const ad1 = await ads.getAd({ input: 'query' });
const ad2 = await ads.getAd({ input: 'query' });
// ad1.id === ad2.id

Seeded Test Mode is useful for snapshot testing and debugging.

Custom Mock Ads

Provide your own mock ads:


const ads = new Ads({
  mock: {
    ads: [
      {
        id: 'test-ad-1',
        headline: 'Test Product',
        body: 'This is a test ad for development',
        disclosure: 'Sponsored',
        cta: {
          label: 'Learn More',
          url: 'https://example.com',
        },
      },
    ],
  },
});

Mock Ad Structure

Mock ads include all standard fields:


interface MockAd {
  id: string;
  headline: string;
  body: string;
  disclosure: string;
  cta: {
    label: string;
    url: string;
  };
  text: string; // Pre-formatted ad block
}

Use Cases

Unit Testing


import { describe, it, expect } from 'vitest';
import Ads from 'notpixel';
 
describe('ad integration', () => {
  it('displays ad correctly', async () => {
    const ads = new Ads({ mock: { seed: 123 } });
    const ad = await ads.getAd({ input: 'test' });
 
    expect(ad).toBeDefined();
    expect(ad.headline).toBeDefined();
  });
});

Development


// dev.ts
const ads = new Ads({
  mock: process.env.NODE_ENV === 'development',
  publisherId: process.env.PUBLISHER_ID,
});

CI/CD Pipeline


# .github/workflows/test.yml
env:
  NOTPIXEL_MOCK: 1
 
steps:
  - run: npm test

Hooks Still Fire

Analytics hooks work in Test Mode:


const ads = new Ads({
  mock: true,
  hooks: {
    onAdFetched: (e) => console.log('Mock ad:', e.ad.id),
  },
});