Timeout Configuration

⏱️ Playwright Timeout Configuration: The Patient Teacher

🎭 The Story of Five Patient Teachers

Imagine you’re in a magical school where five special teachers help you wait for things to happen. Each teacher has their own stopwatch ⏱️ and knows exactly how long to wait before saying “Time’s up!”

These teachers are:

1. Global Teacher - The head principal who sets rules for everyone
2. Navigation Teacher - Waits for pages to load
3. Action Teacher - Waits for clicks and typing
4. Expect Teacher - Waits for things to appear
5. Test Teacher - Waits for entire tests to finish

Let’s meet them all!

🌍 Global Timeout: The Head Principal

The Global Timeout is like the head principal of your school. When the principal sets a rule, everyone follows it unless a specific teacher says otherwise.

What is it?

Global timeout sets the default waiting time for ALL actions in Playwright. It’s the “boss” timeout.

Simple Example

Think of it like this:

• Principal says: “Everyone gets 30 seconds to answer”
• ALL teachers follow this rule by default

// playwright.config.js
export default {
  timeout: 30000,  // 30 seconds for everything
}

Real-Life Analogy

🏫 School Bell: When the principal sets the school day from 8 AM to 3 PM, all classes follow that schedule unless they have special permission.

🚢 Navigation Timeout: The Travel Guide

The Navigation Timeout is like a patient travel guide who waits for you to reach your destination (a new webpage).

What is it?

This timeout controls how long Playwright waits when:

• Going to a new page (page.goto())
• Clicking links that load new pages
• Refreshing the page

Simple Example

Imagine you’re on a boat going to an island:

• Guide says: “I’ll wait 60 seconds for the island to appear”
• If no island after 60 seconds → “We’re lost! Let’s go back!”

// Set navigation timeout
await page.goto('https://example.com', {
  timeout: 60000  // Wait 60 seconds max
});

In Config File

// playwright.config.js
export default {
  use: {
    navigationTimeout: 60000,  // 60 sec for all navigation
  }
}

When Does This Help?

🐢 Slow websites that take time to load 🌐 Bad internet connections 📦 Big pages with lots of images

👆 Action Timeout: The Click Helper

The Action Timeout is like a helper who waits for you to click buttons, type in boxes, or select things.

What is it?

This timeout controls how long Playwright waits for:

• Clicking buttons (click())
• Typing text (fill(), type())
• Checking boxes (check())
• Selecting dropdowns (selectOption())

Simple Example

Imagine you’re at a toy vending machine:

• Helper says: “I’ll wait 10 seconds for the button to work”
• If button doesn’t work in 10 seconds → “Machine is broken!”

// Click with custom timeout
await page.click('#submit-btn', {
  timeout: 10000  // Wait 10 seconds for button
});

// Type with custom timeout
await page.fill('#username', 'player1', {
  timeout: 5000  // Wait 5 seconds
});

In Config File

// playwright.config.js
export default {
  use: {
    actionTimeout: 10000,  // 10 sec for all actions
  }
}

Why Is This Important?

Sometimes buttons are:

• 🔄 Loading (spinning circle)
• 🙈 Hidden behind other things
• ⏳ Not ready yet

🔍 Expect Timeout: The Checker

The Expect Timeout is like a patient checker who waits to see if something appeared correctly on the screen.

What is it?

This timeout controls how long Playwright waits when checking:

• Is this text visible?
• Does this element exist?
• Is this button enabled?

Simple Example

Imagine you planted a seed and you’re waiting for a flower:

• Checker says: “I’ll watch for 5 seconds to see the flower”
• If no flower in 5 seconds → “Nothing grew!”

// Wait for text to appear
await expect(page.locator('.message'))
  .toHaveText('Success!', { timeout: 5000 });

// Wait for element to be visible
await expect(page.locator('#popup'))
  .toBeVisible({ timeout: 3000 });

In Config File

// playwright.config.js
export default {
  expect: {
    timeout: 5000,  // 5 sec for all expect checks
  }
}

Common Uses

✅ Check if success message appeared ✅ Check if error message is gone ✅ Check if loading finished

🧪 Test Timeout: The Exam Proctor

The Test Timeout is like an exam proctor who says “Pencils down!” when time is up for the entire test.

What is it?

This timeout sets how long an entire test can run before Playwright stops it.

Simple Example

Imagine you have a math exam:

• Proctor says: “You have 30 minutes total”
• After 30 minutes → “Time’s up! Submit your answers!”

// playwright.config.js
export default {
  timeout: 30000,  // 30 seconds per test
}

Per-Test Override

// In your test file
test('long test', async ({ page }) => {
  test.setTimeout(120000);  // This test gets 2 minutes
  // ... test code ...
});

Why Is This Needed?

🔄 Infinite loops - Stop tests that run forever 🐛 Broken tests - Stop tests that get stuck ⏰ Time limits - Make sure tests finish reasonably

🎯 The Timeout Family Tree

graph TD
    A["🌍 Global Timeout<br/>Boss of All"] --> B["🚢 Navigation<br/>Page Loading"]
    A --> C["👆 Action<br/>Clicks & Types"]
    A --> D["🔍 Expect<br/>Checking Things"]
    A --> E["🧪 Test<br/>Whole Test Time"]

    style A fill:#667eea,color:#fff
    style B fill:#4ECDC4,color:#fff
    style C fill:#FF6B6B,color:#fff
    style D fill:#95E1D3,color:#000
    style E fill:#F38181,color:#fff

🛠️ Complete Configuration Example

Here’s how all five timeouts work together:

// playwright.config.js
export default {
  // 🧪 Test timeout (entire test)
  timeout: 30000,

  // 🔍 Expect timeout (assertions)
  expect: {
    timeout: 5000,
  },

  use: {
    // 🚢 Navigation timeout
    navigationTimeout: 60000,

    // 👆 Action timeout
    actionTimeout: 10000,
  }
}

📊 Quick Comparison

🎮 Remember This!

Order of Priority (from specific to general):

1. Per-action timeout → Wins first
2. Config timeout → Wins second
3. Global timeout → Default fallback

Example:

// Config says: actionTimeout = 10 seconds
// But this click says: 5 seconds
// 5 seconds wins! ✅
await page.click('#btn', { timeout: 5000 });

🌟 Pro Tips

Tip 1: Start with Defaults

Don’t change timeouts until you have problems. Playwright’s defaults are smart!

Tip 2: Be Generous in CI

Tests run slower in cloud computers. Add extra time:

timeout: process.env.CI ? 60000 : 30000,

Tip 3: Debug with Longer Times

When tests fail, temporarily increase timeouts to see what’s wrong:

test.setTimeout(300000);  // 5 minutes to debug

🎉 You Did It!

Now you know all five timeout teachers:

You’re now a Timeout Master! 🏆

Remember: Timeouts are like patient teachers. They give things time to happen, but not forever. Too short = tests fail for no reason. Too long = tests take forever.

Find the perfect balance! ⚖️