The itgps-agent: Bringing Studio-Managed Configs to Your Local Workflow In Part 1 and Part 2, we explored ITG Playwright Studio's web interface for managing tests. But what if you're a developer who prefers the command line? What if you want to run tests locally during development but still leverage Studio's centralized configuration management? That's exactly what the itgps-agent solves. Here's a common scenario: Your team uses ITG Playwright Studio to manage test configurations, environments, and datasets. Everything works great in CI and for scheduled runs. But when you're developing locally, you're back to managing your own .env files, trying to keep them in sync with what's in the Studio. This leads to: Configuration drift - your local setup doesn't match staging or production Debugging confusion - "It works on my machine" because your env vars are different Onboarding friction - new team members need to manually set up all the environment variables Data duplication - the same credentials and URLs exist in multiple places The itgps-agent is a command-line tool that bridges the gap between local development and Studio-managed configurations. It lets you: Run tests locally with Studio-managed environment variables and datasets Trigger remote test runs on the Studio server from your terminal Sync Git repositories via CLI Work offline with cached Studio data Think of it as "Studio configuration, command-line execution." The agent is distributed as an npm package. Install it globally for the best experience: npm install -g @itechgenie/itgps-agent Or install it locally in your project: npm install --save-dev @itechgenie/itgps-agent Requirements: Node.js 18 or later @playwright/test installed in your project Access to an ITG Playwright Studio instance The first thing you'll do is run the interactive configuration wizard: itgps-agent config This wizard walks you through: Step 1: Studio URL ? Studio URL: https://studio.example.com Step 2: Personal Access Token The wizard provides instructions on how to generate a PAT: Open Studio in your browser Navigate to Settings Scroll to "Personal Access Tokens" Generate a new token Copy and paste it ? Personal Access Token (PAT): ********************** ✓ Verified! Signed in as John Doe ([email protected]) Step 3: Credential Storage Choose where to store your credentials: ? Where to save credentials? > Global config (~/.itgps/config.json) Local .env file Global config: Good if you only work with one Studio instance Local .env: Better for multiple projects or multiple Studio instances Step 4: Project Selection The agent fetches your projects from Studio: ? Select project: > E-Commerce Tests Mobile App Tests API Integration Tests Step 5: Environment & Dataset Choose which environment and dataset to use by default: ? Select environment: > Staging Production Local Development ? Select dataset: > Test Users Edge Cases Performance Data Step 6: Bootstrap & Cache The agent downloads project configuration, environment variables, and dataset variables from Studio and caches them locally: ✓ Bootstrap complete ✓ Playwright config copied to .itgps/playwright.config.cjs ✓ Added .itgps/ to .gitignore Configuration complete! Studio URL: https://studio.example.com User: John Doe ([email protected]) Project: E-Commerce Tests Environment: Staging Dataset: Test Users The config command did several things: Authenticated with Studio using your PAT Stored credentials in either ~/.itgps/config.json or .env Downloaded configuration from Studio (project settings, env vars, dataset vars) Cached data locally in ~/.itgps/cache/ for offline use Copied Playwright config to .itgps/playwright.config.cjs in your project Updated .gitignore to exclude .itgps/ folder Your project structure now looks like: my-test-project/ ├── .itgps/ │ ├── cache/ # Cached Studio data │ └── playwright.config.cjs # Playwright configuration ├── .env # Studio credentials (if you chose local storage) ├── .gitignore # Updated to ignore .itgps/ ├── tests/ │ ├── login.spec.ts │ └── checkout.spec.ts └── package.json Now you can run tests with Studio-managed configuration: itgps-agent test This command: Reads your Studio credentials Fetches the latest configuration (or uses cache if offline) Merges environment variables and dataset variables Runs playwright test with the merged configuration Example output: [Config] Running on browser: chromium Running 5 tests using 1 worker ✓ [chromium] › login.spec.ts:3:5 › User can log in (2.1s) ✓ [chromium] › login.spec.ts:15:5 › Invalid credentials show error (1.8s) ✓ [chromium] › checkout.spec.ts:3:5 › Complete checkout flow (4.3s) ✓ [chromium] › checkout.spec.ts:22:5 › Apply discount code (2.9s) ✓ [chromium] › checkout.spec.ts:35:5 › Guest checkout (3.2s) 5 passed (14.3s) In your test files, you access Studio-managed variables via process.env: // tests/login.spec.js const { test, expect } = require('@playwright/test'); test('user can log in', async ({ page }) => { // These values come from Studio const siteUrl = process.env.siteurl; const username = process.env.app_username; const password = process.env.app_password; await page.goto(siteUrl); await page.fill('#username', username); await page.fill('#password', password); await page.click('#login'); await expect(page).toHaveURL(/dashboard/); }); The agent automatically injects these variables based on the environment and dataset you selected during itgps-agent config. Variables are merged with the following precedence (highest to lowest): Local .env overrides - Variables you define locally Dataset variables - From the selected Studio dataset Environment variables - From the selected Studio environment Project defaults - Default values from Studio project settings This means you can override Studio values locally for debugging: # .env # Override the site URL for local testing siteurl=http://localhost:3000 # Use Studio values for everything else The agent acts as a proxy for Playwright, so all native commands work: # Run tests in headed mode itgps-agent test --headed # Run specific tests itgps-agent test --grep "login" # Run on specific browser itgps-agent test --project=firefox # Generate test code itgps-agent codegen # View reports itgps-agent show-report The agent bootstraps Studio data before passing control to Playwright. Want to trigger a test run on the Studio server from your terminal? itgps-agent remote-run This command: Connects to Studio Lets you select environment and dataset Triggers a test run on the Studio server Streams the output to your terminal in real-time Example: $ itgps-agent remote-run ? Select environment: Staging ? Select dataset: Test Users ? Trigger remote run? Yes ✓ Run triggered. Run ID: e1f86b12-f6b6-42f0-8a17-af6feb89001c [MR] clean output dir ... Running 5 tests using 5 workers ✓ [chromium] › login.spec.ts:3:5 › User can log in (2.3s) ✓ [chromium] › checkout.spec.ts:3:5 › Complete checkout flow (4.1s) ... ✓ Run completed successfully in 12.4s This is useful when: You want to run tests on Studio's infrastructure (more powerful, different OS) You need to test against an environment only accessible from Studio You want the results recorded in Studio's execution history Instruct Studio to pull the latest changes from Git: itgps-agent studio-git-sync This triggers a Git sync on the Studio server, useful in CI/CD pipelines or when you've pushed changes and want Studio to pick them up immediately. The agent caches Studio data locally, so you can work offline: $ itgps-agent test [offline] Using cached Studio data from 2024-05-10T14:23:45Z Running 5 tests using 1 worker ... When you're back online, run itgps-agent config to refresh the cache. The agent copies a Playwright config to .itgps/playwright.config.cjs. This file is fully editable - customize it as needed: // .itgps/playwright.config.cjs const { defineConfig, devices } = require('@playwright/test'); module.exports = defineConfig({ testDir: './', timeout: 30000, // Add custom reporters reporter: [ ['list'], ['html'], ['junit', { outputFile: 'results.xml' }], // Your addition ], // Customize projects projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, }, // Add more browsers as needed ], }); The agent uses this config when running tests. If you run itgps-agent config again, it will ask if you want to overwrite with the latest version from the agent package. The agent works with both JavaScript and TypeScript projects. Your test files can be .spec.js or .spec.ts: TypeScript example: // tests/api.spec.ts import { test, expect } from '@playwright/test'; test('API health check', async ({ request }) => { const apiUrl = process.env.api_base_url!; const apiKey = process.env.api_key!; const response = await request.get(`${apiUrl}/health`, { headers: { 'Authorization': `Bearer ${apiKey}` } }); expect(response.ok()).toBeTruthy(); }); JavaScript example: // tests/api.spec.js const { test, expect } = require('@playwright/test'); test('API health check', async ({ request }) => { const apiUrl = process.env.api_base_url; const apiKey = process.env.api_key; const response = await request.get(`${apiUrl}/health`, { headers: { 'Authorization': `Bearer ${apiKey}` } }); expect(response.ok()).toBeTruthy(); }); Both work identically with the agent. Here's how a typical development workflow looks with the agent: Morning: Start Development # Pull latest code git pull # Refresh Studio config (in case env vars changed) itgps-agent config # Run tests to ensure everything works itgps-agent test During Development # Run specific test you're working on itgps-agent test tests/new-feature.spec.ts --headed # Override a variable locally for debugging echo "debug_mode=true" >> .env itgps-agent test tests/new-feature.spec.ts Before Committing # Run full test suite itgps-agent test # If all pass, commit and push git add . git commit -m "Add new feature tests" git push After Pushing # Trigger Studio to sync with Git itgps-agent studio-git-sync # Trigger a remote run to verify in Studio environment itgps-agent remote-run Authentication Errors: # Token expired or invalid # Regenerate token in Studio and reconfigure itgps-agent config Network Errors: # Studio unreachable # Agent automatically uses cached data [offline] Using cached Studio data from 2024-05-10T14:23:45Z Missing Browsers: # Playwright browsers not installed npx playwright install Config Issues: # Regenerate config file itgps-agent config # Choose "Yes" when asked to overwrite Global Config (~/.itgps/config.json): { "studioUrl": "https://studio.example.com", "token": "your-personal-access-token" } Local Environment (.env): ITGPS_STUDIO_URL=https://studio.example.com ITGPS_TOKEN=your-personal-access-token ITGPS_PROJECT_ID=project-uuid ITGPS_ENV_ID=environment-uuid ITGPS_DATASET_ID=dataset-uuid # Local overrides siteurl=http://localhost:3000 debug_mode=true Cache Location (~/.itgps/cache/): ~/.itgps/ ├── config.json # Global credentials └── cache/ ├── project.json # Project list ├── environments.json # Environment configs └── datasets.json # Dataset variables The agent is particularly valuable when: You prefer command-line tools but want centralized config management You're developing locally and need the same env vars as CI/Studio You work on multiple projects with different Studio instances You need offline capability but want to sync when online You want to trigger remote runs without opening the browser Your team uses Studio but you want a local development workflow The beauty of the itgps-agent is that it gives you flexibility: Use the Studio web interface for scheduling, viewing reports, and managing configurations Use the agent CLI for local development and command-line workflows Use both - they work together seamlessly Your tests remain standard Playwright tests. The agent just makes it easier to run them with the right configuration, whether you're working locally or triggering remote runs. Install the agent and give it a try: # Install globally npm install -g @itechgenie/itgps-agent # Configure connection to Studio itgps-agent config # Run tests itgps-agent test For more details, check out: GitHub: https://github.com/ITechGenie/itg-playwright-studio Agent README: https://github.com/ITechGenie/itg-playwright-studio/tree/main/itgps-agent Studio Documentation: https://github.com/ITechGenie/itg-playwright-studio#readme Series Recap In this three-part series, we've covered: Part 1: Why managing Playwright tests at scale is challenging and how ITG Playwright Studio addresses these challenges Part 2: A detailed visual tour of the Studio interface, showing how to manage tests, view reports, schedule runs, and manage data Part 3 (this article): How to use the itgps-agent CLI tool to run tests locally while leveraging Studio-managed configurations Together, ITG Playwright Studio and the itgps-agent provide a complete solution for managing Playwright tests at scale - whether you prefer a web interface or command-line tools. Have you tried the itgps-agent? What features would you like to see added? Let me know in the comments!