Universal GAS Testing Framework

Multi-Project Testing Framework for Google Apps Script projects with AI Agent Integration for zero-configuration setup.

🚀 Multi-Project Architecture

This framework supports testing multiple GAS projects from a single installation at your repository root:

your_repository/
├── gas_testing_framework/          # Git submodule at root
│   ├── configs/                    # Project configurations
│   │   ├── project_name.config.js
│   │   └── template.config.js
│   ├── projects/                   # Project-specific results
│   │   ├── project_name/
│   │   │   ├── results/
│   │   │   └── project_resources.json
│   └── .env                        # Shared authentication
├── path/to/project1/gas_code/
├── path/to/project2/gas_code/
└── path/to/projectN/gas_code/

Quick Setup (Multi-Project)

# 1. Add framework as git submodule to repository root
git submodule add https://github.com/vladimir-ks/gas_testing_framework.git
cd gas_testing_framework

# 2. Install dependencies
npm install

# 3. Configure shared authentication
cp config/example_config.env .env
# Edit .env with your GAS_AUTH_TOKEN and Google API credentials

# 4. Setup your first project
npm run setup --project=my_project --gas-path=./path/to/gas/code

# 5. Test setup
npm run test --project=my_project --check-setup

# 6. Run tests
npm run test --project=my_project

🤖 AI Agent Integration (Multi-Project Automation)

This framework includes AI agent capabilities for completely automated testing configuration across multiple projects:

For Users: AI Agent Setup

1. Complete multi-project setup (steps 1-3 above)
2. For each project you want to test:

   # Let AI agent analyze and configure project
   npm run ai-setup --project=project_name --gas-path=./path/to/gas/code

3. Give your AI agent the AI_AGENT_README.md file - it contains complete instructions
4. Let the AI agent handle the rest!

For AI Agents: Multi-Project Capabilities

• Read: AI_AGENT_README.md for complete multi-project workflow
• Analyze: Multiple GAS projects from their configured paths
• Configure: Auto-generate project-specific test configurations
• Initialize: Create test resources (Google Sheets, etc.) per project
• Test: Execute comprehensive testing across all projects
• Compare: Generate comparative reports across projects

What AI Agents Can Do (Multi-Project)

• ✅ Auto-analyze multiple GAS project structures simultaneously
• ✅ Auto-configure appropriate test strategies per project
• ✅ Auto-generate custom test scenarios for each project
• ✅ Resource management - create and manage test resources per project
• ✅ Cross-project comparison and optimization recommendations
• ✅ Batch testing with comprehensive reporting

Required Configuration

Shared Authentication (.env)

Variable	Where to get it
GAS_AUTH_TOKEN	Run: gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/script.projects" then gcloud auth application-default print-access-token
GOOGLE_OAUTH_CLIENT_ID	Google Cloud Console → APIs & Services → Credentials
GOOGLE_OAUTH_CLIENT_SECRET	Google Cloud Console → APIs & Services → Credentials

Project-Specific Configuration

Each project requires its own configuration file in configs/project_name.config.js:

Setting	Description	Example
paths.gas_code	Relative path to GAS code directory	./n8n_code_node/gas_etl_system/gas_etl_GAS_code
project.type	Type of GAS project	webapp, addon, standalone
project.main_functions	Primary entry point functions	['doGet', 'doPost', 'processQueue']

Project Resources (Auto-Created)

Each project gets its own resources in projects/project_name/project_resources.json:

• Test Google Spreadsheet ID
• GAS Script ID
• Deployment tracking
• Custom test endpoints

Available Commands (Multi-Project)

Core Testing Commands

Command	Description
npm run test	List all available projects
npm run test --project=project_name	Test specific project
npm run test --all-projects	Test all configured projects
npm run test --project=project_name --suite=crud	Run specific test suite

GAS ETL System Shortcuts

Command	Description
npm run test:gas-etl	Test the gas_etl_system project
npm run setup:gas-etl	Setup gas_etl_system project
npm run deploy-test:gas-etl	Deploy and test gas_etl_system
npm run crud:gas-etl	Run CRUD tests for JobLog v4
npm run performance:gas-etl	Run performance tests for ETL operations
npm run errors:gas-etl	Test error handling and queue processing
npm run integrity:gas-etl	Test data integrity for all 11 sheet types
npm run cache:gas-etl	Test cache invalidation and rebuild

Setup and Configuration

Command	Description
npm run setup --project=name --gas-path=./path	Setup new project configuration
npm run list-projects	Show all configured projects
npm run validate-config --project=name	Validate project configuration
npm run init-resources --project=name	Create test resources for project

Advanced Operations

Command	Description
npm run deploy-test --project=name	Deploy and test specific project
npm run compare --projects=proj1,proj2	Compare results across projects
npm run clean --project=name	Clean project test results
npm run ai-setup --project=name --gas-path=./path	AI-powered project setup

Legacy Single-Project Commands

Command	Description
node run_tests.js --help	Show all available legacy commands
node run_tests.js --check-setup	Verify single-project setup
node run_tests.js --deploy-and-test	Deploy and test (legacy mode)

Featured Project: GAS ETL System (JobLog v4)

The framework is pre-configured with a comprehensive test suite for the GAS ETL System - a high-performance ETL pipeline for JobLog v4 data with queue processing and 11 sheet types.

JobLog v4 Features Tested

• 11 Sheet Types: log_id, projects, users, tasks, subtasks, records, expenses, inventory, learnings_log, files, scheduling
• Queue Processing: Async job queuing with lock management
• Cache Management: Header mapping and ID caching with invalidation
• Complex Relationships: Tasks → Subtasks, nested entity linking
• CRUD Operations: Create, Read, Update, Delete with UPSERT support
• Error Recovery: Webhook notifications and graceful failure handling

Quick Start: GAS ETL System

# 1. Setup the project
npm run setup:gas-etl

# 2. Run comprehensive tests
npm run test:gas-etl

# 3. Test specific functionality
npm run crud:gas-etl        # Test all CRUD operations
npm run performance:gas-etl  # Test queue processing speed
npm run cache:gas-etl        # Test cache invalidation

GAS ETL System Configuration

The framework automatically detects:

• GAS Code Path: ../n8n_code_node/gas_etl_system/gas_etl_GAS_code
• Spreadsheet Schema: 11 sheet types with proper relationships
• Test Data: Realistic JobLog v4 data with all entity types
• Performance Thresholds: Queue processing, cache hits, response times

Test Suites

• CRUD: Basic create/read/update/delete operations
• Performance: Response time and throughput tests
• Error Handling: Error response validation
• Data Integrity: Data consistency checks
• Cache: Caching behavior tests

Deployment Tracking

The framework automatically tracks deployment IDs:

• After each clasp deploy, the new deployment ID is saved to config/deployment_version.json
• Tests use the latest deployment automatically
• Previous deployments are archived in the same file

Documentation

Multi-Project Setup

• Multi-Project Setup Guide - Complete multi-project installation
• Project Configuration Guide - Creating and managing project configs
• Resource Management Guide - Managing test resources per project
• Migration Guide - Migrating from single-project setup

AI Agent Integration

• AI Agent Instructions - For AI agents: Multi-project automation workflow
• AI Agent Usage - Human guide to AI automation

Reference Documentation

• CLI Reference - Complete command reference
• Setup Guide - Legacy single-project setup

Multi-Project Workflow: Human + AI Agent

1. Human: Repository setup with git submodule and shared authentication
2. AI Agent: Multi-project analysis, configuration, and resource creation
3. Human: Review project configurations and test results
4. Ongoing: AI agent handles regression testing and cross-project optimization

Key Benefits

• 🏗️ Centralized Testing: One framework installation for all GAS projects
• 🔄 Independent Versioning: Framework updates don't affect your project code
• 📊 Cross-Project Analysis: Compare performance and quality across projects
• 🤖 AI-Powered Setup: Automated configuration and resource management
• 📈 Scalable Architecture: Easy to add new projects and test suites

The framework handles timing, retries, and reporting automatically across all your projects - with AI integration making multi-project configuration completely automated.