Synthetic Monitoring: Puppeteer Script to Login and Verify UI

Hey team, Darian here. Let’s talk about something that used to keep me up at night: the “silent failure.” You know the one—all your infrastructure metrics are green, CPU is nominal, memory looks fine, but the user login flow is completely broken. I once spent an entire morning debugging a “site down” alert only to find that a CSS change had hidden the login button on mobile. That’s when I decided to stop checking things manually and start automating UI verification. This simple Puppeteer script is the result, and it has saved me countless hours. It acts like a real user, ensuring the critical paths of our application actually work.

Prerequisites

• Node.js and npm installed on your machine or monitoring server.
• A basic understanding of JavaScript and CSS selectors.
• A target web application you have permission to test.

The Guide: Building Your UI Watchdog

I’ll skip the standard project setup steps like creating a directory and running `npm init`. You’ve got your own workflow for that. Just make sure you run `npm install puppeteer` and `npm install dotenv` in your project folder to get the necessary packages. Let’s dive right into the code.

Step 1: Secure Your Credentials with a `config.env` File

First rule: never hardcode secrets. It’s a massive security risk. We’ll use a `config.env` file to store our login credentials. In your project directory, create a file named `config.env`.

# config.env
TEST_USERNAME="your-test-username"
TEST_PASSWORD="your-secure-password"
LOGIN_URL="https://app.your-service.com/login"

Pro Tip: Always use dedicated, low-privilege test accounts for synthetic monitoring. Never use a real user’s account or an admin account. If the credentials for this script ever leak, you want the potential damage to be minimal.

Step 2: The Script Boilerplate

Now, let’s create our main script file. I’ll call it `checkLogin.js`. We’ll start by importing our libraries and setting up the basic asynchronous function structure. We use an `async` function because nearly every Puppeteer action is a promise that we need to `await`.

// checkLogin.js
const puppeteer = require('puppeteer');
require('dotenv').config({ path: 'config.env' });

async function checkLoginFlow() {
    console.log('Starting UI verification check...');
    let browser = null; // Define browser outside the try block to access it in finally

    try {
        // Launch a headless browser. Set headless: false to watch it run.
        browser = await puppeteer.launch({ headless: true });
        const page = await browser.newPage();
        
        // The rest of our logic will go here

        console.log('UI verification successful.');

    } catch (error) {
        console.error('UI verification failed:', error.message);
        // This is crucial for CI/CD or alerting systems
        process.exit(1); 
    } finally {
        if (browser) {
            await browser.close();
            console.log('Browser closed.');
        }
    }
}

checkLoginFlow();

The `try…catch…finally` block is essential for robust scripting. It ensures that no matter what happens—success or failure—the browser instance is always closed. You don’t want dozens of zombie Chrome processes eating up your server’s memory.

Step 3: Simulating the Login

Inside our `try` block, let’s add the logic to navigate to the login page and fill out the form. The key here is using CSS selectors to find the right input fields and buttons. You can find these by using the “Inspect” tool in your own web browser.

// Inside the 'try' block, after creating the 'page' object

const URL = process.env.LOGIN_URL;
await page.goto(URL, { waitUntil: 'networkidle2' });

console.log(`Navigated to ${URL}`);

// Find elements and type credentials
await page.type('#username', process.env.TEST_USERNAME);
await page.type('#password', process.env.TEST_PASSWORD);

console.log('Credentials entered.');

// Click the login button and wait for the page to navigate
await Promise.all([
    page.click('button[type="submit"]'),
    page.waitForNavigation({ waitUntil: 'networkidle2' }),
]);

console.log('Login form submitted.');

The `Promise.all` with `page.click` and `page.waitForNavigation` is a robust way to handle logins. It tells Puppeteer to “click this button, and then wait for the resulting page load to complete before moving on.”

Step 4: Verifying the Post-Login UI

This is the most important part. Getting to the dashboard isn’t enough; we need to prove it loaded correctly. The best way is to look for an element that *only* exists after a successful login. This could be a “Welcome, User” message, a logout button, or a specific dashboard widget.

// Add this after the login submission logic

console.log('Verifying dashboard UI...');
const dashboardElementSelector = '#user-dashboard-widget'; // Change this to a real selector from your app
const welcomeMessage = await page.waitForSelector(dashboardElementSelector, { timeout: 10000 });

if (!welcomeMessage) {
    // If the element is not found after the timeout, an error will be thrown and caught.
    // We can add an explicit throw for clarity.
    throw new Error(`Verification failed: Could not find element '${dashboardElementSelector}' post-login.`);
}

const pageTitle = await page.title();
console.log(`Successfully landed on page: "${pageTitle}"`);

Pro Tip: Don’t check for something generic like a `<div>` tag. Be specific. A selector like `header .user-profile-menu` or an element with a `data-testid` attribute is much more reliable and less likely to break during minor UI redesigns.

Step 5: Scheduling the Check

To make this a true synthetic monitor, you need to run it on a schedule. On a Linux server, a simple cron job does the trick. You can set it to run every 15 minutes, every hour, or whatever suits your needs. Your cron command would look something like this, running the script at the top of every hour.

0 * * * * node /path/to/your/project/checkLogin.js >> /path/to/your/logs/ui-check.log 2>&1

This command runs the script and appends all output (both standard and error) to a log file, which is perfect for auditing and debugging.

Common Pitfalls (And How I’ve Learned to Avoid Them)

• Brittle Selectors: The biggest reason these scripts fail is that the UI changes and our selectors (`#username`, `button[type=”submit”]`) no longer match. I now work with our front-end devs to add stable `data-testid` attributes to key elements specifically for automation. It makes scripts a thousand times more resilient.
• Race Conditions: Sometimes you try to click a button that hasn’t appeared yet. Always use `page.waitForSelector()` before interacting with an element if you suspect it might be loaded dynamically by JavaScript.
• CAPTCHAs and MFA: These are designed to stop bots, and guess what? Our script is a bot. For test environments, I always have a configuration that disables these features for our specific test user or IP range. Don’t try to solve CAPTCHAs in your script; bypass them at the application level.

Conclusion

And there you have it. This script is a simple but powerful watchdog that provides real user-level confidence in your application’s most critical path. It’s not a replacement for traditional monitoring, but an essential layer on top of it. Adapt the selectors to your own application, hook it up to an alerting system, and you can rest a little easier knowing your login flow is being verified around the clock.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions