Setting Up Playwright Locally for Hyperping Browser Checks

This comprehensive guide will help you set up a local development environment that mirrors Hyperping's Browser Check infrastructure, enabling you to develop and test your Playwright monitoring scripts before deploying them to production.

Hyperping's Browser Check feature utilizes Playwright version 1.33.0 with a carefully curated set of packages to ensure consistent and reliable end-to-end monitoring across distributed virtual machines.

Installing Playwright with Version Matching

Create a new directory for your Hyperping browser check development and install the exact versions used by Hyperping's infrastructure:

mkdir hyperping-browser-checks
cd hyperping-browser-checks
npm init -y

# Install exact Playwright versions used by Hyperping
npm install playwright@1.33.0 @playwright/test@1.33.0

# Install the complete Hyperping package ecosystem
npm install typescript@^5.0.4 expect@^27.5.1 uuid@^9.0.0 lodash@4.17.21 moment@^2.29.4 axios@^1.4.0 btoa@1.2.1 jsonwebtoken@^9.0.0 date-fns@^2.30.0 crypto-js@^4.1.1

# Download browser binaries
npx playwright install

Project Structure and Configuration

Establish a well-organized project structure that facilitates easy development and testing. Create the essential configuration files that mirror Hyperping's expected environment.

Playwright Configuration

Create a playwright.config.js file that matches Hyperping's runtime settings, including the critical 2-minute timeout limit:

const config = {
  globalTimeout: 120 * 1000, // 2 minutes to match Hyperping's limit
  workers: 1,
  expect: {
    timeout: 120 * 1000 // 2 minutes for assertions
  },
  projects: [
    {
      name: 'chromium',
      use: {
        userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.5672.53 Safari/537.36',
        viewport: { width: 1280, height: 720 },
        screen: { width: 1920, height: 1080 },
        deviceScaleFactor: 1,
        isMobile: false,
        hasTouch: false,
        defaultBrowserType: 'chromium'
      }
    }
  ]
};

export default config;

Basic Test Example

Here's a simple test to get you started. This example shows basic Playwright functionality without requiring any environment variables or complex setup:

import { test, expect } from '@playwright/test';

test('Check website title and content', async ({ page }) => {
  // Navigate to a website
  await page.goto('https://example.com');
  
  // Check the page title
  await expect(page).toHaveTitle(/Example Domain/);
  
  // Verify some content is visible
  await expect(page.locator('h1')).toContainText('Example Domain');
  
  // Check that a link is present
  await expect(page.locator('a[href*="iana.org"]')).toBeVisible();
});

Running Tests Visually (Non-Headless Mode)

While Hyperping runs tests in headless mode for performance, during local development you can run tests with a visible browser to see exactly what's happening. This is extremely helpful for debugging and understanding how your tests interact with the page.

To run tests with a visible browser window, use the --headed flag:

npx playwright test --headed

For even more control and debugging capabilities, you can use the --debug flag which opens the Playwright Inspector:

npx playwright test --debug

The debug mode allows you to:

• Step through your test line by line
• Inspect elements on the page
• See exactly where your test fails
• Modify selectors in real-time

Environment Variables and Security

For more advanced scenarios involving authentication or sensitive data, you can use environment variables to match Hyperping's security model:

# .env file for local testing
EMAIL=your-test-email@example.com
PASSWORD=your-test-password
API_KEY=your-api-key
API_SECRET=your-api-secret
BASE_URL=https://your-application.com

Developing and Testing Browser Checks

When developing browser checks locally, structure your tests to match the patterns expected by Hyperping's monitoring system. Focus on creating robust, reliable checks that can withstand network variations and minor application changes.

Complex Workflow Example

Implement proper error handling and meaningful assertions that provide clear information about failures:

import { test, expect } from '@playwright/test';
import axios from 'axios';
import moment from 'moment';
import _ from 'lodash';

test('E-commerce checkout process', async ({ page }) => {
  // Set extended timeout for complex workflows
  test.setTimeout(120000);
  
  try {
    // Navigate to the application
    await page.goto(process.env.BASE_URL);
    
    // Add product to cart
    await page.click('[data-testid="add-to-cart"]');
    await expect(page.locator('.cart-count')).toHaveText('1');
    
    // Proceed to checkout
    await page.click('[data-testid="checkout-button"]');
    await expect(page.locator('h1')).toContainText('Checkout');
    
    // Fill payment information
    await page.fill('#credit-card', '4111111111111111');
    await page.fill('#expiry', '12/25');
    await page.fill('#cvv', '123');
    
    // Submit order
    await page.click('#submit-order');
    await expect(page.locator('.success-message')).toBeVisible();
    
  } catch (error) {
    console.error('Checkout process failed:', error.message);
    throw error;
  }
});

Advanced Testing Patterns

Leverage the full capabilities of Hyperping's package ecosystem to create sophisticated monitoring scenarios. Utilize libraries like axios for API validation, moment for date manipulation, and lodash for data processing:

import { test, expect } from '@playwright/test';
import axios from 'axios';
import moment from 'moment';
import _ from 'lodash';

test('API and UI consistency check', async ({ page }) => {
  // Fetch data via API
  const apiResponse = await axios.get(`${process.env.BASE_URL}/api/products`, {
    headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` }
  });
  
  const apiProducts = apiResponse.data;
  
  // Navigate to UI and verify consistency
  await page.goto(`${process.env.BASE_URL}/products`);
  
  const uiProducts = await page.locator('.product-item').allTextContents();
  
  // Use lodash to compare data structures
  const apiProductNames = _.map(apiProducts, 'name');
  expect(uiProducts.length).toBe(apiProductNames.length);
  
  // Verify recent products using moment
  const recentProducts = _.filter(apiProducts, product => {
    return moment(product.created_at).isAfter(moment().subtract(7, 'days'));
  });
  
  expect(recentProducts.length).toBeGreaterThan(0);
});

Testing and Debugging Locally

Run your browser checks locally using Playwright's built-in test runner, which provides comprehensive debugging capabilities and detailed execution reports:

# Run all tests
npx playwright test

# Run specific test file
npx playwright test tests/checkout.spec.ts

# Run with debugging enabled
npx playwright test --debug

# Generate and view test report
npx playwright show-report

Utilize Playwright's trace viewer and screenshot capabilities to debug complex scenarios. These tools provide visual feedback about test execution and help identify the exact point of failure in your monitoring scripts.

Available Packages in Hyperping Environment

Your local environment includes the same packages available in Hyperping's runtime:

• playwright ^1.33.0
• @playwright/test 1.33
• typescript ^5.0.4
• expect ^27.5.1
• uuid ^9.0.0
• lodash 4.17.21
• moment ^2.29.4
• axios ^1.4.0
• btoa 1.2.1
• jsonwebtoken ^9.0.0
• date-fns ^2.30.0
• crypto-js ^4.1.1

Migration to Hyperping

Once your browser checks are working reliably in your local environment, migrating them to Hyperping is straightforward:

1. Copy your test code directly into Hyperping's browser check editor
2. Configure environment variables in the Hyperping interface
3. Test your monitor to ensure it works correctly
4. Enable monitoring with your desired frequency

The identical package versions and runtime environment guarantee that your locally tested scripts will execute correctly in production.

Best Practices

• Timeout Management: Always consider the 2-minute global timeout when designing complex workflows
• Error Handling: Implement comprehensive try-catch blocks with meaningful error messages
• Selector Strategy: Use stable selectors (data-testid, role-based) rather than fragile CSS selectors
• Environment Consistency: Test with the same environment variables you'll use in production
• Double Check Feature: Remember that Hyperping automatically retries failed checks, so design tests accordingly

This local development approach minimizes deployment risks and maximizes the effectiveness of your monitoring strategy, ultimately leading to more reliable detection of critical issues in your applications.