DEV Community

Cover image for The itgps-agent: Bringing Studio-Managed Configs to Your Local Workflow
Prakash
Prakash

Posted on

The itgps-agent: Bringing Studio-Managed Configs to Your Local Workflow

#playwright #testing #automation #cli

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.

The Problem: Configuration Drift

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 Solution: itgps-agent

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."

Installation

The agent is distributed as an npm package. Install it globally for the best experience:

npm install -g @itechgenie/itgps-agent
Enter fullscreen mode Exit fullscreen mode

Or install it locally in your project:

npm install --save-dev @itechgenie/itgps-agent
Enter fullscreen mode Exit fullscreen mode

Requirements:

  • Node.js 18 or later
  • @playwright/test installed in your project
  • Access to an ITG Playwright Studio instance

Initial Setup: The Config Command

The first thing you'll do is run the interactive configuration wizard:

itgps-agent config
Enter fullscreen mode Exit fullscreen mode

This wizard walks you through:

Step 1: Studio URL

? Studio URL: https://studio.example.com
Enter fullscreen mode Exit fullscreen mode

Step 2: Personal Access Token

The wizard provides instructions on how to generate a PAT:

  1. Open Studio in your browser
  2. Navigate to Settings
  3. Scroll to "Personal Access Tokens"
  4. Generate a new token
  5. Copy and paste it 
? Personal Access Token (PAT): **********************
✓ Verified! Signed in as John Doe (john@example.com)
Enter fullscreen mode Exit fullscreen mode

Step 3: Credential Storage

Choose where to store your credentials:

? Where to save credentials?
  > Global config (~/.itgps/config.json)
    Local .env file
Enter fullscreen mode Exit fullscreen mode
  • 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 (john@example.com)
  Project:     E-Commerce Tests
  Environment: Staging
  Dataset:     Test Users
Enter fullscreen mode Exit fullscreen mode

What Just Happened?

The config command did several things:

  1. Authenticated with Studio using your PAT
  2. Stored credentials in either ~/.itgps/config.json or .env
  3. Downloaded configuration from Studio (project settings, env vars, dataset vars)
  4. Cached data locally in ~/.itgps/cache/ for offline use
  5. Copied Playwright config to .itgps/playwright.config.cjs in your project
  6. 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
Enter fullscreen mode Exit fullscreen mode

Running Tests Locally

Now you can run tests with Studio-managed configuration:

itgps-agent test
Enter fullscreen mode Exit fullscreen mode

This command:

  1. Reads your Studio credentials
  2. Fetches the latest configuration (or uses cache if offline)
  3. Merges environment variables and dataset variables
  4. 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)
Enter fullscreen mode Exit fullscreen mode

Using Studio Variables in Tests

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/);
});
Enter fullscreen mode Exit fullscreen mode

The agent automatically injects these variables based on the environment and dataset you selected during itgps-agent config.

Variable Precedence

Variables are merged with the following precedence (highest to lowest):

  1. Local .env overrides - Variables you define locally
  2. Dataset variables - From the selected Studio dataset
  3. Environment variables - From the selected Studio environment
  4. 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
Enter fullscreen mode Exit fullscreen mode

All Playwright Commands Work

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
Enter fullscreen mode Exit fullscreen mode

The agent bootstraps Studio data before passing control to Playwright.

Remote Execution: Trigger Studio Runs

Want to trigger a test run on the Studio server from your terminal?

itgps-agent remote-run
Enter fullscreen mode Exit fullscreen mode

This command:

  1. Connects to Studio
  2. Lets you select environment and dataset
  3. Triggers a test run on the Studio server
  4. 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
Enter fullscreen mode Exit fullscreen mode

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

Git Sync from CLI

Instruct Studio to pull the latest changes from Git:

itgps-agent studio-git-sync
Enter fullscreen mode Exit fullscreen mode

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.

Offline Support

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
...
Enter fullscreen mode Exit fullscreen mode

When you're back online, run itgps-agent config to refresh the cache.

Customizing the Playwright Config

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
  ],
});
Enter fullscreen mode Exit fullscreen mode

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.

Language Support: JavaScript and TypeScript

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();
});
Enter fullscreen mode Exit fullscreen mode

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();
});
Enter fullscreen mode Exit fullscreen mode

Both work identically with the agent.

Real-World Workflow

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Authentication Errors:

# Token expired or invalid
# Regenerate token in Studio and reconfigure
itgps-agent config
Enter fullscreen mode Exit fullscreen mode

Network Errors:

# Studio unreachable
# Agent automatically uses cached data
[offline] Using cached Studio data from 2024-05-10T14:23:45Z
Enter fullscreen mode Exit fullscreen mode

Missing Browsers:

# Playwright browsers not installed
npx playwright install
Enter fullscreen mode Exit fullscreen mode

Config Issues:

# Regenerate config file
itgps-agent config
# Choose "Yes" when asked to overwrite
Enter fullscreen mode Exit fullscreen mode

Configuration Files Reference

Global Config (~/.itgps/config.json):

{
  "studioUrl": "https://studio.example.com",
  "token": "your-personal-access-token"
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Cache Location (~/.itgps/cache/):

~/.itgps/
├── config.json          # Global credentials
└── cache/
    ├── project.json     # Project list
    ├── environments.json # Environment configs
    └── datasets.json    # Dataset variables
Enter fullscreen mode Exit fullscreen mode

Why Use the Agent?

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 Best of Both Worlds

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.

Try It Yourself

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
Enter fullscreen mode Exit fullscreen mode

For more details, check out:

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!

Top comments (0)