# Apps Script MCP Testing Guide
This document provides instructions for running unit tests and end-to-end (E2E) tests for the Apps Script MCP feature.
## Test Structure
```
tests/gappsscript/
__init__.py
test_apps_script_tools.py # Unit tests with mocked API
manual_test.py # E2E tests against real API
```
## Unit Tests
Unit tests use mocked API responses and do not require Google credentials.
### Running Unit Tests
```bash
# Run all Apps Script unit tests
uv run pytest tests/gappsscript/test_apps_script_tools.py -v
# Run specific test
uv run pytest tests/gappsscript/test_apps_script_tools.py::test_list_script_projects -v
# Run with coverage
uv run pytest tests/gappsscript/test_apps_script_tools.py --cov=gappsscript
```
### Test Coverage
Unit tests cover:
- list_script_projects (uses Drive API)
- get_script_project
- get_script_content
- create_script_project
- update_script_content
- run_script_function
- create_deployment
- list_deployments
- update_deployment
- delete_deployment
- list_script_processes
## E2E Tests
E2E tests interact with the real Google Apps Script API. They require valid OAuth credentials and will create real resources in your Google account.
### Prerequisites
1. **Google Cloud Project** with Apps Script API and Drive API enabled
2. **OAuth credentials** (Desktop application type)
3. **Test user** added to OAuth consent screen
### Setup
**Option 1: Default paths (recommended for CI)**
Place credentials in the project root:
```bash
# Place your OAuth client credentials here
cp /path/to/your/client_secret.json ./client_secret.json
```
**Option 2: Custom paths via environment variables**
```bash
export GOOGLE_CLIENT_SECRET_PATH=/path/to/client_secret.json
export GOOGLE_TOKEN_PATH=/path/to/token.pickle
```
### Running E2E Tests
```bash
# Interactive mode (prompts for confirmation)
uv run python tests/gappsscript/manual_test.py
# Non-interactive mode (for CI)
uv run python tests/gappsscript/manual_test.py --yes
```
### E2E Test Flow
The test script performs the following operations:
1. **List Projects** - Lists existing Apps Script projects via Drive API
2. **Create Project** - Creates a new test project
3. **Get Project** - Retrieves project details
4. **Update Content** - Adds code to the project
5. **Run Function** - Attempts to execute a function (see note below)
6. **Create Deployment** - Creates a versioned deployment
7. **List Deployments** - Lists all deployments
8. **List Processes** - Lists recent script executions
### Cleanup
The test script does not automatically delete created projects. After running tests:
1. Go to [Google Apps Script](https://script.google.com/)
2. Find projects named "MCP Test Project"
3. Delete them manually via the menu (three dots) > Remove
## Headless Linux Testing
For headless environments (servers, CI/CD, WSL without GUI):
### OAuth Authentication Flow
The test script uses a headless-compatible OAuth flow:
1. Script prints an authorization URL
2. Open the URL in any browser (can be on a different machine)
3. Complete Google sign-in and authorization
4. Browser redirects to `http://localhost/?code=...` (page will not load)
5. Copy the full URL from the browser address bar
6. Paste it into the terminal when prompted
### Example Session
```
$ python tests/gappsscript/manual_test.py --yes
============================================================
HEADLESS AUTH
============================================================
1. Open this URL in any browser:
https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=...
2. Sign in and authorize the app
3. You'll be redirected to http://localhost (won't load)
4. Copy the FULL URL from browser address bar
(looks like: http://localhost/?code=4/0A...&scope=...)
5. Paste it below:
Paste full redirect URL: http://localhost/?code=4/0AQSTgQ...&scope=...
Building API services...
=== Test: List Projects ===
Found 3 Apps Script projects:
...
```
### Credential Storage
OAuth tokens are stored as pickle files:
- Default: `./test_token.pickle` in project root
- Custom: Set via `GOOGLE_TOKEN_PATH` environment variable
Tokens are reused on subsequent runs until they expire or are revoked.
## Known Limitations and Caveats
### run_script_function Test Failure
The "Run Function" test will fail with a 404 error unless you manually configure the script as an API Executable. This is a Google platform requirement, not a bug.
To make run_script_function work:
1. Open the created test script in Apps Script editor
2. Go to Project Settings > Change GCP project
3. Enter your GCP project number
4. Deploy as "API Executable"
For E2E testing purposes, it is acceptable for this test to fail. All other tests should pass.
### Drive API Requirement
The `list_script_projects` function uses the Google Drive API (not the Apps Script API) because the Apps Script API does not provide a projects.list endpoint. Ensure the Drive API is enabled in your GCP project.
### Scope Requirements
The E2E tests require these scopes:
- `script.projects` and `script.projects.readonly`
- `script.deployments` and `script.deployments.readonly`
- `script.processes`
- `drive.readonly`
If you encounter "insufficient scopes" errors, delete the stored token file and re-authenticate.
### Rate Limits
Google enforces rate limits on the Apps Script API. If running tests repeatedly, you may encounter quota errors. Wait a few minutes before retrying.
## CI/CD Integration
For automated testing in CI/CD pipelines:
### Unit Tests Only (Recommended)
```yaml
# GitHub Actions example
- name: Run unit tests
run: uv run pytest tests/gappsscript/test_apps_script_tools.py -v
```
### E2E Tests in CI
E2E tests require OAuth credentials. Options:
1. **Skip E2E in CI** - Run only unit tests in CI, run E2E locally
2. **Service Account** - Not supported (Apps Script API requires user OAuth)
3. **Pre-authenticated Token** - Store encrypted token in CI secrets
To use a pre-authenticated token:
```bash
# Generate token locally
python tests/gappsscript/manual_test.py
# Store test_token.pickle contents as base64 in CI secret
base64 test_token.pickle > token.b64
# In CI, restore and set path
echo $TOKEN_SECRET | base64 -d > test_token.pickle
export GOOGLE_TOKEN_PATH=./test_token.pickle
python tests/gappsscript/manual_test.py --yes
```
Note: Tokens expire and must be refreshed periodically.
## Troubleshooting
### "Apps Script API has not been used in project"
Enable the Apps Script API in your GCP project:
https://console.cloud.google.com/flows/enableapi?apiid=script.googleapis.com
### "Access Not Configured. Drive API has not been used"
Enable the Drive API in your GCP project:
https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com
### "Request had insufficient authentication scopes"
Delete the token file and re-authenticate:
```bash
rm test_token.pickle
python tests/gappsscript/manual_test.py
```
### "User is not authorized to access this resource"
Ensure your email is added as a test user in the OAuth consent screen configuration.
### "Requested entity was not found" (404 on run)
The script needs to be deployed as "API Executable". See the run_script_function section above.
### OAuth redirect fails on headless machine
The redirect to `http://localhost` is expected to fail. Copy the URL from the browser address bar (including the error page URL) and paste it into the terminal.
