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

In , 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:

CODE

npm install -g @itechgenie/itgps-agent

Or install it locally in your project:

CODE

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

Initial Setup: The Config Command

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

CODE

itgps-agent config

This wizard walks you through:

Step 1: Studio URL

CODE

? 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

CODE

? Personal Access Token (PAT): **********************

✓ Verified! Signed in as John Doe ([email protected])

Step 3: Credential Storage

Choose where to store your credentials:

CODE

? 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:

CODE

? Select project:

  > E-Commerce Tests

    Mobile App Tests

    API Integration Tests

Step 5: Environment & Dataset

Choose which environment and dataset to use by default:

CODE

? 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:

CODE

✓ 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

What Just Happened?

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:

CODE

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

Running Tests Locally

Now you can run tests with Studio-managed configuration:

CODE

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:

CODE

[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)

Using Studio Variables in Tests

In your test files, you access Studio-managed variables via process.env:

    CODE      
// 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.

Variable Precedence

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:

CODE

# .env

# Override the site URL for local testing

siteurl=http://localhost:3000



# Use Studio values for everything else

All Playwright Commands Work

The agent acts as a proxy for Playwright, so all native commands work:

    CODE      
# 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.

Remote Execution: Trigger Studio Runs

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

CODE

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:

    CODE      
$ 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

Git Sync from CLI

Instruct Studio to pull the latest changes from Git:

CODE

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.

Offline Support

The agent caches Studio data locally, so you can work offline:

    CODE      
$ 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.

Customizing the Playwright Config

The agent copies a Playwright config to .itgps/playwright.config.cjs. This file is fully editable - customize it as needed:

    CODE      
// .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.

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:

    CODE      
// 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:

    CODE      
// 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.

Real-World Workflow

Here's how a typical development workflow looks with the agent:

Morning: Start Development

    CODE      
# 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

    CODE      
# 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

    CODE      
# 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

CODE

# Trigger Studio to sync with Git

itgps-agent studio-git-sync



# Trigger a remote run to verify in Studio environment

itgps-agent remote-run

Troubleshooting

Authentication Errors:

CODE

# Token expired or invalid

# Regenerate token in Studio and reconfigure

itgps-agent config

Network Errors:

    CODE      
# Studio unreachable

# Agent automatically uses cached data

[offline] Using cached Studio data from 2024-05-10T14:23:45Z

Missing Browsers:

CODE

# Playwright browsers not installed

npx playwright install

Config Issues:

CODE

# Regenerate config file

itgps-agent config

# Choose "Yes" when asked to overwrite

Configuration Files Reference

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

    CODE      
{

  "studioUrl": "https://studio.example.com",

  "token": "your-personal-access-token"

}

Local Environment (.env):

CODE

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/):

CODE

~/.itgps/

├── config.json          # Global credentials

└── cache/

    ├── project.json     # Project list

    ├── environments.json # Environment configs

    └── datasets.json    # Dataset variables

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:

    CODE      
# 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:

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!

Vollständiger Original-Bericht

Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

↗ Original-Artikel auf dev.to lesen