Enable and disable tests directly from a Google Spreadsheet — no code changes required.

Skipper integrates with your existing test suite via a minimal config. Each test is identified by its file path + title. Set a disabledUntil date in the spreadsheet to skip a test until that date; leave it empty (or set a past date) to run it normally.

• read-only mode (default): Skipper reads the spreadsheet at the start of the test run and skips any test whose disabledUntil date is in the future.
• sync mode (SKIPPER_MODE=sync): Same as read-only, plus after the run Skipper reconciles the spreadsheet — adding rows for new tests and, when SKIPPER_SYNC_ALLOW_DELETE=true, removing rows for tests no longer in the suite.

Create a Google Spreadsheet with the following columns in the first row (header):

• testId — {relative file path} > {describe blocks} > {test name}, automatically generated by the plugin.
• disabledUntil — ISO 8601 date (e.g. 2026-04-01). Empty or past date = test runs. Future date = test is skipped.
• notes — optional free-text field, ignored by the plugin.

All Skipper plugins accept the same SkipperConfig object:

// Base64-encoded JSON (recommended for CI)
credentials: { credentialsBase64: process.env.GOOGLE_CREDS_B64! }

// Path to a local JSON file (recommended for local dev)
credentials: { credentialsFile: './service-account.json' }

// Raw service account object
credentials: { client_email: '...', private_key: '...' }

By default Skipper uses the first tab of the spreadsheet. Use sheetName to target a specific tab:

{
  spreadsheetId: '...',
  credentials: { credentialsBase64: '...' },
  sheetName: 'E2E Tests', // reads and writes to this tab only
}

Additional sheet tabs to read (never written to). Useful for sharing a common list of disabled tests across multiple suites. When the same testId appears in more than one sheet, the most restrictive (latest future) disabledUntil wins:

{
  spreadsheetId: '...',
  credentials: { credentialsBase64: '...' },
  sheetName: 'E2E Tests',        // primary sheet (read + write in sync mode)
  referenceSheets: ['Shared'],   // additional sheets (read-only)
}

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Navigate to APIs & Services → Library
4. Search for Google Sheets API and enable it

1. Navigate to APIs & Services → Credentials
2. Click Create Credentials → Service Account
3. Give it a name (e.g. skipper-bot) and click Done
4. Click on the service account → Keys tab → Add Key → Create new key → JSON
5. Download the JSON file — keep it secret

Open your Google Spreadsheet and share it with the service account email (found in the JSON file as client_email):

• Viewer role for read-only mode
• Editor role for sync mode

Convert the JSON file to a base64 string for use as a CI secret:

base64 -i service-account.json | tr -d '\n'

Save the output as a secret named GOOGLE_CREDS_B64 in your CI environment (e.g. GitHub Actions secrets).

For local development, keep the JSON file and reference it via credentialsFile:

credentials: { credentialsFile: './service-account.json' }

Run your test suite in sync mode once to auto-populate all test rows:

SKIPPER_MODE=sync SKIPPER_SPREADSHEET_ID=<your-spreadsheet-id> pnpm test

All tests will be added to the spreadsheet with an empty disabledUntil (enabled by default). You can then set dates in the spreadsheet to disable specific tests.

No env var needed. Tests with a future disabledUntil are skipped.

SKIPPER_SPREADSHEET_ID=<id> pnpm test

SKIPPER_MODE=sync SKIPPER_SPREADSHEET_ID=<id> pnpm test

After the run:

• New tests → added to the spreadsheet with empty disabledUntil
• Removed tests → warned (set SKIPPER_SYNC_ALLOW_DELETE=true to also delete them)

# .github/workflows/test.yml
name: Test

on:
  pull_request:
  push:
    branches: [main]

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

      - run: pnpm install

      - name: Test (read-only on PR)
        if: github.event_name == 'pull_request'
        env:
          SKIPPER_SPREADSHEET_ID: ${{ secrets.SKIPPER_SPREADSHEET_ID }}
          GOOGLE_CREDS_B64: ${{ secrets.GOOGLE_CREDS_B64 }}
        run: pnpm test

      - name: Test + sync (on merge to main)
        if: github.ref == 'refs/heads/main'
        env:
          SKIPPER_MODE: sync
          SKIPPER_SPREADSHEET_ID: ${{ secrets.SKIPPER_SPREADSHEET_ID }}
          GOOGLE_CREDS_B64: ${{ secrets.GOOGLE_CREDS_B64 }}
        run: pnpm test

MIT — see LICENSE.