他の導入ガイド(全7件)

test-mock / 導入ガイド

@ciderjs/vitest-plugin-gas-mock

Vitest用にGAS専用メソッドのモックをグローバルに注入

npm install -D @ciderjs/vitest-plugin-gas-mock
このページの内容

@ciderjs/vitest-plugin-gas-mock は、Google Apps Script (GAS) のローカル開発において、Vitest のテスト環境に GAS のグローバルオブジェクトや Enum を自動注入するプラグインです。@types/google-apps-script の型定義から事前生成されたメタデータと Proxy ベースのファクトリを組み合わせることで、複雑な事前設定なしにメソッドチェーンやスパイ検証、型安全な戻り値のカスタマイズを提供します。

概要と特徴

GAS のサーバーサイドコードは SpreadsheetApp や DriveApp などのグローバルオブジェクトに強く依存しており、ローカルの Node.js 環境(Vitest)で単体テストを実行する際には膨大なモック定義が必要になります。本プラグインは GAS 特有の深いメソッドチェーンや名前空間の解決を自動化し、テストコードの本質的なロジック検証に集中できる環境を構築します。

  • ゼロコンフィグのグローバルモック注入: vitest.config.ts にプラグインを追加するだけで、SpreadsheetApp や DriveApp などの GAS グローバルオブジェクトがテスト環境で利用可能になります。
  • メソッドチェーンの自動解決: SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Sheet1').getRange('A1') のような深いメソッドチェーンが、追加のモック定義なしで自動的に繋がります。
  • Vitest スパイの標準統合: 各メソッドは内部的に vi.fn() として生成・キャッシュされるため、toHaveBeenCalled() や toHaveBeenCalledWith() などの標準マッチャーでそのまま検証できます。
  • 型安全なチェーン制御 (mockChain): ドット区切りの文字列パスから TypeScript の型を再帰的に推論し、固定値の返却やコールバック関数による動的な振る舞いを型補完付きで定義できます。
  • 名前空間の自動分離: SpreadsheetApp 経由の Range と DocumentApp 経由の Range のように、同名で構造が異なるインターフェースを呼び出し元のコンテキストに応じて自動的に判別します。

動作要件

  • Vitest: ^4.0.0(Peer Dependency)
  • TypeScript 型定義: 型補完および mockChain の型推論を利用する場合は、プロジェクトに @types/google-apps-script がインストールされている必要があります。

インストール

パッケージマネージャーを使用して開発依存関係(devDependencies)にインストールします。TypeScript を使用する場合は @types/google-apps-script もあわせて導入してください。

.sh
# pnpm
pnpm add -D @ciderjs/vitest-plugin-gas-mock vitest @types/google-apps-script

# npm
npm install -D @ciderjs/vitest-plugin-gas-mock vitest @types/google-apps-script

# yarn
yarn add -D @ciderjs/vitest-plugin-gas-mock vitest @types/google-apps-script

クイックスタート

1. Vitest の設定

vitest.config.ts に mockGas プラグインを追加します。本プラグインは Vitest の config フックを通じてセットアップファイル(@ciderjs/vitest-plugin-gas-mock/setup)を test.setupFiles に自動登録します。

vitest.config.ts
.ts
import { defineConfig } from 'vitest/config';
import { mockGas } from '@ciderjs/vitest-plugin-gas-mock';

export default defineConfig({
  plugins: [mockGas()],
  test: {
    globals: true,
  },
});

2. TypeScript の設定

テストコード内で SpreadsheetApp などのグローバル変数や vitest のグローバル API に型を適用するため、tsconfig.json の compilerOptions.types に以下を指定します。

tsconfig.json
.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["vitest/globals", "google-apps-script"]
  }
}

3. テストの作成と実行

テストファイル内で GAS のグローバルオブジェクトに直接アクセスし、メソッドチェーンの実行と vi.fn() スパイによる引数検証を行えます。各スパイには SpreadsheetApp.getActiveSpreadsheet.getSheetByName のようにパス名に基づいた mockName が自動付与されます。

tests/spreadsheet.test.ts
.ts
import { describe, expect, it } from 'vitest';

describe('Spreadsheet 操作のテスト', () => {
  it('メソッドチェーンの実行と引数検証ができること', () => {
    const ss = SpreadsheetApp.getActiveSpreadsheet();
    const sheet = ss.getSheetByName('Sales');
    const range = sheet?.getRange('A1:B10');

    expect(ss).toBeDefined();
    expect(sheet).toBeDefined();
    expect(range).toBeDefined();

    expect(SpreadsheetApp.getActiveSpreadsheet).toHaveBeenCalled();
    expect(ss.getSheetByName).toHaveBeenCalledWith('Sales');
    expect(sheet?.getRange).toHaveBeenCalledWith('A1:B10');
  });
});

基本的な使い方

mockChain による固定値のオーバーライド

特定のメソッド呼び出しパスに対して戻り値を定義するには、mockChain ヘルパー関数を使用します。第1引数にドット区切りのメソッドパス(途中の () は省略)、第2引数に返却したい値を指定します。

tests/override.test.ts
.ts
import { expect, it } from 'vitest';
import { mockChain } from '@ciderjs/vitest-plugin-gas-mock';

it('指定したパスの戻り値を固定値で上書きする', () => {
  mockChain('SpreadsheetApp.getActiveSpreadsheet.getName', '月次レポート');
  mockChain(
    'SpreadsheetApp.getActiveSpreadsheet.getActiveSheet.getLastRow',
    42,
  );

  const ss = SpreadsheetApp.getActiveSpreadsheet();
  expect(ss.getName()).toBe('月次レポート');
  expect(ss.getActiveSheet().getLastRow()).toBe(42);
});

コールバック関数による動的なモック

mockChain の第2引数に関数を渡すと、テスト対象コードからそのメソッドが呼び出された際に、実引数をそのまま受け取って動的に戻り値を生成できます。引数に応じた条件分岐、呼び出し回数のカウントなどの副作用、例外(エラー)のスローをテストする場合に有効です。

tests/dynamic.test.ts
.ts
import { expect, it } from 'vitest';
import { mockChain } from '@ciderjs/vitest-plugin-gas-mock';

it('引数に応じて戻り値を動的に切り替える', () => {
  mockChain('SpreadsheetApp.openById', (id) => {
    if (id === 'invalid_id') {
      throw new Error('Spreadsheet not found');
    }
    return {
      getId: () => id,
      getName: () => `Book_${id}`,
    };
  });

  expect(() => SpreadsheetApp.openById('invalid_id')).toThrow(
    'Spreadsheet not found',
  );

  const ss = SpreadsheetApp.openById('abc_123');
  expect(ss.getId()).toBe('abc_123');
  expect(ss.getName()).toBe('Book_abc_123');
});

部分オブジェクト (DeepPartial) の返却

mockChain の戻り値型には DeepPartial<R> が適用されています。そのため、Sheet や Spreadsheet のような多数のメソッドを持つインターフェースを返すメソッドをモックする場合でも、テストで実際に使用するメソッドだけを定義したオブジェクトを返すことができ、TypeScript の型エラーは発生しません。

tests/partial.test.ts
.ts
import { expect, it } from 'vitest';
import { mockChain } from '@ciderjs/vitest-plugin-gas-mock';

it('必要なメソッドのみを持つ部分オブジェクトを返却する', () => {
  mockChain('SpreadsheetApp.getActiveSpreadsheet.getSheetByName', (name) => {
    if (name === 'NotFound') {
      return null;
    }
    return {
      getName: () => `Sheet: ${name}`,
    };
  });

  const ss = SpreadsheetApp.getActiveSpreadsheet();
  expect(ss.getSheetByName('NotFound')).toBeNull();
  expect(ss.getSheetByName('Users')?.getName()).toBe('Sheet: Users');
});

Enum の参照

GAS の Enum は、グローバルスコープからの直接参照と、SpreadsheetApp.BorderStyle のような親サービスを経由した参照の両方に対応しています。Enum の各メンバーにはメンバー名と同じ文字列(または定義された定数値)が格納されています。

tests/enum.test.ts
.ts
import { expect, it } from 'vitest';

it('Enum にアクセスできること', () => {
  expect(BorderStyle.SOLID).toBe('SOLID');
  expect(SpreadsheetApp.BorderStyle.SOLID).toBe('SOLID');
  expect(SpreadsheetApp.Direction.UP).toBe('UP');
});

API リファレンス

mockGas()

Vitest に GAS モックのセットアップ処理を登録するプラグイン関数です。

index.d.ts
.ts
function mockGas(): Plugin;
  • 戻り値: vitest/config の Plugin オブジェクト(プラグイン名: 'vite-plugin-gasmock')
  • 動作: Vitest の設定(config.test.setupFiles)に @ciderjs/vitest-plugin-gas-mock/setup を追加します。既に他の setupFiles が設定されている場合は、既存の設定を維持したまま末尾に追加します。

mockChain(path, value)

指定したメソッドチェーンのパスに対する戻り値またはコールバック実装を登録します。

index.d.ts
.ts
function mockChain<P extends string, Target = Get<GasRegistry, P>>(
  path: P,
  value: Target extends (...args: infer Args) => infer R
    ? ((...args: Args) => DeepPartial<R>) | DeepPartial<R>
    : DeepPartial<Target> | any,
): void;
プロパティ / 引数 型 デフォルト 説明
path P extends string - 'SpreadsheetApp.getActiveSpreadsheet.getName' のようなドット区切りの文字列パス。
value ((...args: Args) => DeepPartial<R>) | DeepPartial<R> - パス末端のメソッドが返すべき値(DeepPartial<R>)、またはメソッド呼び出し時の引数を受け取るコールバック関数。

型推論対応サービス一覧 (GasRegistry)

mockChain で文字列パスからの厳密な型推論(引数型および戻り値型の推論)が有効になるトップレベルサービスは以下の13種類です。

サービス名 対応する型定義 (GoogleAppsScript.*)
SpreadsheetApp GoogleAppsScript.Spreadsheet.SpreadsheetApp
DriveApp GoogleAppsScript.Drive.DriveApp
DocumentApp GoogleAppsScript.Document.DocumentApp
SlidesApp GoogleAppsScript.Slides.SlidesApp
FormApp GoogleAppsScript.Forms.FormApp
GmailApp GoogleAppsScript.Gmail.GmailApp
CalendarApp GoogleAppsScript.Calendar.CalendarApp
ContactsApp GoogleAppsScript.Contacts.ContactsApp
UrlFetchApp GoogleAppsScript.URL_Fetch.UrlFetchApp
PropertiesService GoogleAppsScript.Properties.PropertiesService
CacheService GoogleAppsScript.Cache.CacheService
LockService GoogleAppsScript.Lock.LockService
Utilities GoogleAppsScript.Utilities.Utilities

上記以外のグローバルオブジェクト(Session, Logger, ScriptApp, HtmlService, CardService 等)も実行時には globalThis に自動注入され、mockChain によるパスの上書きも動作しますが、TypeScript 上では Target が never となり第2引数が any として扱われます。

アーキテクチャと動作仕様

デフォルトの戻り値仕様

mockChain で戻り値を明示的に上書きしていない場合、各メソッドやプロパティは @types/google-apps-script の戻り値型定義に基づいて以下のデフォルト値を自動的に返します。

型定義上の戻り値型 デフォルトの戻り値 該当メソッドの例
string / String / Char '' (空文字) Spreadsheet.getName(), Range.getA1Notation()
number / Number / Integer / Byte 0 Sheet.getLastRow(), Range.getRow()
boolean / Boolean false Range.isBlank(), Sheet.isSheetHidden()
void undefined SpreadsheetApp.flush(), Sheet.clear()
Date / Base.Date new Date() (実行時の日時インスタンス) CalendarEvent.getStartTime()
object / any / インデックス型 ({ [key: string]: ... }) {} (空オブジェクト) Properties.getProperties()
GAS のインターフェース・クラス 次の階層を保持する新規 Proxy モック SpreadsheetApp.getActiveSpreadsheet()
1次元配列 (T[]) [デフォルト値またはモック] (要素数1の配列) Spreadsheet.getSheets(), Drive.Folder.getEditors()
2次元配列 (T[][]) [[デフォルト値またはモック]] (1x1の2次元配列) Range.getValues(), Range.getDisplayValues()
tests/defaults.test.ts
.ts
import { expect, it } from 'vitest';

it('未設定時は型に応じたデフォルト値が返る', () => {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  expect(ss.getName()).toBe('');

  const sheet = ss.getActiveSheet();
  expect(sheet.getLastRow()).toBe(0);

  const values = sheet.getRange('A1:B2').getValues();
  expect(values).toEqual([[{}]]);
});

名前空間の自動分離

GAS の型定義には、複数のサービス間で同じ名前を持つインターフェースが存在します(例:Spreadsheet.Range と Document.Range)。本ライブラリは呼び出し経路のプレフィックス(SpreadsheetApp, DocumentApp, SlidesApp, FormApp, GmailApp, DriveApp, CalendarApp)を追跡し、それぞれのサービス名前空間に属するクラス定義を優先的に解決します。

tests/namespace.test.ts
.ts
import { expect, it } from 'vitest';

it('Spreadsheet と Document の Range が区別される', () => {
  const ssRange = SpreadsheetApp.getActiveSpreadsheet().getRange('A1');
  expect(typeof ssRange.getValue).toBe('function');

  const docRange = DocumentApp.create('SampleDoc').newRange();
  expect(typeof docRange.getRangeElements).toBe('function');
  expect((docRange as any).getValue).toBeUndefined();
});

グローバル注入から除外されるオブジェクト

JavaScript やテストランタイム(Node.js / DOM 環境)の標準機能を破壊しないよう、以下のオブジェクト名は GAS の型定義に存在していても globalThis への自動注入から除外(ブラックリスト登録)されています。また、既に globalThis に同名のプロパティが存在する場合も上書きを行いません。

  • 除外対象リスト: Date, Math, JSON, Object, Function, Array, String, Number, Boolean, RegExp, Error, Map, Set, WeakMap, WeakSet, Promise, Symbol, Proxy, Reflect, Element, Event, Node, Document, Window, console

制限事項と注意点

  • mockChain のオーバーライド状態の管理: mockChain で登録した設定はモジュール内部のレジストリ(Map)に保持されます。あるテストケースで設定した mockChain の値が後続のテストケースに影響を与えないよう、同じパスを複数のテストで利用する場合は各テスト内で明示的に mockChain を再設定するか、beforeEach 等でデフォルト値に戻す運用を推奨します。
  • mockChain で部分オブジェクトを返した場合のチェーン: mockChain で手動のオブジェクト(例:{ getName: () => 'Test' })を返した場合、その戻り値は自動生成された Proxy ではなくユーザーが返したプレーンオブジェクトそのものになります。後続のコードでさらに別メソッドを呼び出す場合は、返却するオブジェクト内に必要なメソッドを含めて定義してください。
  • メソッドのオーバーロードと型推論: GAS の API には同名で引数構成が異なるオーバーロードメソッドが多数存在します(例:Sheet.getRange)。TypeScript の条件型の仕様上、mockChain のコールバック引数の型推論では最後のオーバーロード定義が採用されます。異なる引数パターンのオーバーロードをコールバックで扱う場合は、コールバック引数に明示的な型アノテーションまたはオプショナル引数を指定してください。

ライセンス

MIT License