gas-sandbox

Run Google Apps Script projects locally with a sandboxed spreadsheet environment, mock HTTP services, and XLSX export.

Features

• Sandbox execution — Run .gs functions in an isolated Node.js VM with full SpreadsheetApp, UrlFetchApp, PropertiesService, ScriptApp, and Utilities shims.
• Mock HTTP responses — Define canned responses for UrlFetchApp.fetch() calls so your scripts never hit real endpoints during testing.
• HTTP capture — Record live API responses and export them as mock files with built-in PII masking.
• JSON / XLSX export — Export the in-memory spreadsheet to JSON or .xlsx files.
• .env support — Loads .env and .env.local files so PropertiesService returns your local config values.
• Test helpers — createTestRunner, buildSheetData, assertSheet, and more for writing tests against your GAS project.

Install

npm install gas-sandbox

Or run directly:

npx gas-sandbox -p ./my-gas-project -r main

Quick Start

import { GASRunner } from 'gas-sandbox';

const runner = new GASRunner({
  httpMode: 'mock',
  skipSleep: true,
  mockResponses: {
    'api.example.com/data': { statusCode: 200, body: { items: [1, 2, 3] } }
  }
});

runner.loadProject('./my-gas-project');
runner.run('processData');
runner.exportXlsx('output.xlsx');

CLI

gas-sandbox --project <dir> --run <function> [options]

Examples

# List all functions in a project
gas-sandbox -p ./my-gas-project --list

# Run with mock HTTP and export to XLSX
gas-sandbox -p ./my-gas-project -r processData --mock-file mocks.json --output-xlsx report.xlsx

# Run live and export JSON + XLSX
gas-sandbox -p ./my-gas-project -r fetchReport --skip-sleep -o data.json --output-xlsx report.xlsx

# Capture live responses with PII masking
gas-sandbox -p ./my-gas-project -r fetchData --capture-mocks mocks.json --mask-emails --mask-fields name,userId

Programmatic API

GASRunner

import { GASRunner } from 'gas-sandbox';

Constructor Options

interface GASRunnerOptions {
  httpMode?: 'mock' | 'live' | 'capture';
  skipSleep?: boolean;
  mockResponses?: Record<string, MockResponse>;
  envPath?: string;
  projectDir?: string;
}

Methods

Types

interface MockResponse {
  statusCode?: number;
  body?: unknown;
}

interface SpreadsheetJSON {
  sheets: Record<string, { data: CellValue[][] }>;
}

Mock HTTP

Inline mock responses

const runner = new GASRunner({
  httpMode: 'mock',
  mockResponses: {
    'api.example.com/users': {
      statusCode: 200,
      body: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
    }
  }
});

URL matching is substring-based — 'api.example.com/users' matches any URL containing that string.

Mock file (JSON)

Create a mocks.json:

{
  "api.example.com/users": {
    "statusCode": 200,
    "body": [{ "id": 1, "name": "Alice" }]
  }
}

gas-sandbox -p ./my-gas-project -r fetchUsers --mock-file mocks.json

HTTP Capture & Masking

Record live API responses during execution, then replay them offline. Masking options sanitize PII before saving.

Capture workflow

# 1. Record real API responses with PII masked
gas-sandbox -p ./my-gas-project -r fetchData \
  --capture-mocks mocks.json \
  --mask-emails --mask-fields name,userId

# 2. Replay offline in tests — no API calls
gas-sandbox -p ./my-gas-project -r fetchData \
  --mock-file mocks.json --skip-sleep

Masking options

Programmatic capture

import { GASRunner, DataMasker } from 'gas-sandbox';

const runner = new GASRunner({ httpMode: 'capture', skipSleep: true });
runner.loadProject('./my-gas-project');
runner.run('fetchData');

runner.exportMocks('mocks.json', {
  emails: true,
  fields: ['name', 'userId'],
});

XLSX Export

CLI

gas-sandbox -p ./my-gas-project -r generateReport --output-xlsx report.xlsx

Programmatic

runner.loadProject('./my-gas-project');
runner.run('buildReport');
runner.exportXlsx('report.xlsx');

The exported file contains one worksheet per in-memory sheet, preserving sheet names and cell values.

Environment

gas-sandbox loads environment variables in this order (later files override earlier ones):

1. System environment variables
2. .env in the project directory
3. .env.local in the project directory
4. Custom path via --env <path> flag

Variables are available through PropertiesService.getScriptProperties():

// In your .gs code
var token = PropertiesService.getScriptProperties().getProperty('API_TOKEN');

Test Helpers

gas-sandbox exports utilities for writing tests against your GAS project:

import {
  createTestRunner,
  buildSheetData,
  assertSheet,
  assertCell,
  getSheetAsRecords,
  runAndNormalize,
  cleanupTestEnv,
} from 'gas-sandbox';

Example test

import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { createTestRunner, buildSheetData, runAndNormalize, cleanupTestEnv } from 'gas-sandbox';

describe('My GAS project', () => {
  afterEach(() => cleanupTestEnv(['API_TOKEN']));

  it('processes data correctly', () => {
    const runner = createTestRunner({
      projectDir: './my-gas-project',
      data: buildSheetData({
        'Raw Data': {
          headers: ['Name', 'Score'],
          rows: [['Alice', 95], ['Bob', 87]],
        }
      }),
      mockResponses: {
        'api.example.com/config': { statusCode: 200, body: { threshold: 90 } }
      },
      env: { API_TOKEN: 'test-token' },
    });

    const result = runAndNormalize(runner, 'processScores');
    assert.equal(result.aboveThreshold, 1);
  });
});

Using in Your GAS Project

1. Install gas-sandbox:

   npm init -y && npm install -D gas-sandbox tsx @types/node

2. Create .env.local next to your .gs files with API keys:

   API_TOKEN=Bearer your-token-here

3. Capture mock data from a live run:

   npx gas-sandbox -p . -r myFunction --capture-mocks mocks.json --mask-emails --mask-fields name

4. Write tests at test/my-project.test.ts using the captured mocks.

5. Add scripts to package.json:

   {
     "scripts": {
       "test": "tsx --test test/*.test.ts",
       "run": "gas-sandbox -p . -r myFunction --skip-sleep",
       "run:export": "gas-sandbox -p . -r myFunction --skip-sleep --output-xlsx report.xlsx",
       "run:mock": "gas-sandbox -p . -r myFunction --mock-file mocks.json --skip-sleep",
       "capture": "gas-sandbox -p . -r myFunction --capture-mocks mocks.json --mask-emails --mask-fields name"
     }
   }

6. Run:

   npm test              # Run tests with mocked data
   npm run run:export    # Live run with XLSX export
   npm run run:mock      # Offline run with captured mocks
   npm run capture       # Re-capture fresh mock data