feat: improve error handling in setup methods for Browser, Context, and Page for TUnit.Playwright

[thomhurst]

This pull request introduces improvements to error handling in Playwright test setup and updates the GitHub Actions workflow to ensure Playwright dependencies and browsers are correctly installed. The key changes include adding validation checks to prevent uninitialized objects during test setup and enhancing the CI configuration for Playwright.

Improvements to error handling in Playwright test setup:

• TUnit.Playwright/BrowserTest.cs: Added a validation check in BrowserSetup to throw an InvalidOperationException if BrowserType is not initialized, ensuring proper setup of the Playwright environment.
• TUnit.Playwright/ContextTest.cs: Added a validation check in ContextSetup to throw an InvalidOperationException if Browser is not initialized, preventing issues when creating a new browser context.
• TUnit.Playwright/PageTest.cs: Added a validation check in PageSetup to throw an InvalidOperationException if Context is not initialized, ensuring a valid browser context is available before creating a new page.

Enhancements to GitHub Actions workflow:

• .github/workflows/dotnet.yml: Added a step to install Playwright browsers (npx playwright install) after installing Playwright dependencies, ensuring the required browsers are available during CI runs.

[claude]

Claude finished @thomhurst's task —— View job

---

PR Review: Improve error handling in setup methods for Browser, Context, and Page for TUnit.Playwright

Review Tasks:

• Read and analyze all changed files
• Review error handling improvements in Playwright setup methods
• Analyze GitHub Actions workflow changes
• Provide feedback on code quality and best practices
• Check for potential bugs or issues
• Assess performance considerations
• Review security concerns
• Evaluate test coverage

---

Overall Assessment ✅

This PR introduces well-designed error handling improvements that provide clear diagnostic information when Playwright setup fails. The changes are defensive, minimal, and focused on improving the developer experience.

Code Quality & Best Practices ⭐

Strengths:

• Clear error messages: The validation checks provide specific, actionable error messages that guide developers to the root cause
• Consistent pattern: All three files follow the same validation pattern, making the codebase predictable
• Proper exception type: Using InvalidOperationException is appropriate for state validation errors
• Fail-fast approach: Catching initialization issues early prevents cascading failures

Error Message Analysis:

• BrowserTest.cs:32-36: Excellent error message referencing both Playwright initialization and PlaywrightSetup execution
• ContextTest.cs:22-26: Good reference to the prerequisite BrowserSetup method
• PageTest.cs:13-17: Clear indication that ContextSetup is the dependency

Potential Issues & Improvements 🔍

Minor Observations:

1. Inheritance Chain Validation: The current approach validates immediate dependencies but doesn't validate the full chain. For example, PageTest only checks Context but not Browser or BrowserType. This is actually good design - each class is responsible for its immediate dependency.

2. Async Method Pattern: All validation is done synchronously at the start of async methods, which is the correct pattern for fail-fast validation.

3. Error Message Consistency: The error messages could be slightly more consistent:

   • BrowserTest: "BrowserType is not initialized"
   • ContextTest: "Browser is not initialized"
   • PageTest: "Browser context is not initialized"

   Consider standardizing to "X is not initialized" format.

Performance Considerations ⚡

Positive Impact:

• Null checks are extremely fast (O(1))
• Failing fast prevents expensive Playwright operations when setup is incomplete
• No performance overhead when everything is working correctly

Security Concerns 🔒

No security issues identified:

• Error messages don't expose sensitive information
• No additional attack surface introduced
• Validation logic is straightforward with no complex input handling

GitHub Actions Workflow Changes ✅

.github/workflows/dotnet.yml:63-65:

- name: Install Playwright Browsers
  run: npx playwright install

Analysis:

• Correct addition: Installing browsers after dependencies is the proper sequence
• Cross-platform compatibility: npx playwright install works on all matrix OS targets (ubuntu, windows, macos)
• CI reliability: This addresses potential CI failures where browsers weren't available

Test Coverage Assessment 📋

Current Coverage:
The error handling paths are straightforward but should be tested:

Recommendations for future testing:

1. Unit tests for validation logic:

   [Test]
   public async Task BrowserSetup_ThrowsWhenBrowserTypeIsNull()
   {
       var browserTest = new BrowserTest();
       // Simulate uninitialized state
       Assert.ThrowsAsync<InvalidOperationException>(() => browserTest.BrowserSetup());
   }

2. Integration tests for setup sequence:

   • Test that proper initialization sequence works
   • Test that skipped setup steps cause appropriate failures

Suggested Future Enhancements 💡

1. Structured logging: Consider adding structured logs before throwing exceptions for better debugging
2. Setup state tracking: Consider adding a setup state enum to track which steps completed
3. Diagnostic helper: A method to check setup state could be useful for debugging

Summary

This is a high-quality PR that significantly improves the developer experience with Playwright test setup. The changes are:

• ✅ Safe: No risk of breaking existing functionality
• ✅ Helpful: Clear error messages for common setup issues
• ✅ Consistent: Follows established patterns
• ✅ Minimal: Focused scope with no unnecessary complexity

The GitHub Actions improvement ensures CI reliability for Playwright tests.

Recommendation: Approved - This PR successfully achieves its goal of improving error handling with minimal risk and maximum benefit.