PSPlaywright

Work in Progress & Experimentation

This project is currently a work in progress and serves as an experiment in using GitHub Copilot to generate PowerShell modules for browser automation. The code, structure, and documentation are actively evolving as new features and improvements are explored. Feedback and contributions are welcome!

PSPlaywright is a PowerShell module that provides a set of commands for browser automation and web testing using Microsoft Playwright. It enables users to control browsers, interact with web pages, and automate UI testing scenarios directly from PowerShell scripts.

About Microsoft Playwright

Microsoft Playwright is a Node.js library for browser automation. It supports Chromium, Firefox, and WebKit, allowing for cross-browser web automation and testing. Playwright enables reliable end-to-end testing for modern web applications, supporting features like headless execution, network interception, and advanced page interactions.

Commands

Browser Commands

• Start-PlaywrightBrowser - Start a new browser instance
• Stop-PlaywrightBrowser - Stop the browser instance
• Enter-PlaywrightBrowser - Enter a browser context
• Exit-PlaywrightBrowser - Exit the browser context
• Open-PlaywrightPage - Open a new page in the browser

Page Commands

The following Page cmdlets are available:

• Add-PlaywrightPageInitScript - Add an initialization script to the page
• Add-PlaywrightPageLocatorHandler - Add a locator handler to the page
• Set-PlaywrightPageToFront - Bring the page to the front
• Close-PlaywrightPage - Close the current page
• Get-PlaywrightPageContent - Get the content of the page
• Set-PlaywrightPageDragAndDrop - Perform drag and drop on the page
• Set-PlaywrightPageMedia - Emulate media features on the page
• Enter-PlaywrightPage - Enter the page context
• Get-PlaywrightPageJavascriptHandle - Evaluate JavaScript and get a handle
• Exit-PlaywrightPage - Exit the page context
• Find-PlaywrightPageElement - Find an element on the page
• Open-PlaywrightPageUrl - Navigate to a URL
• Invoke-PlaywrightPageJavascript - Invoke JavaScript on the page
• Invoke-PlaywrightPageKeyboard - Send keyboard input to the page
• Invoke-PlaywrightPageMouse - Send mouse input to the page
• Get-PlaywrightPageOpener - Get the opener of the page
• Invoke-PlaywrightPageNavigation - Handle page navigation
• Suspend-PlaywrightPage - Pause the page
• Get-PlaywrightPagePdf - Generate a PDF of the page
• Reset-PlaywrightPage - Reload the current page
• Remove-PlaywrightPageLocatorHandler - Remove a locator handler from the page
• Invoke-PlaywrightPageGarageCollection - Request garbage collection on the page
• Get-PlaywrightPageScreenshot - Take a screenshot of the page
• Set-PlaywrightPageContent - Set the HTML content of the page
• Set-PlaywrightPageViewportSize - Set the viewport size of the page
• Get-PlaywrightPageTitle - Get the title of the page
• Wait-PlaywrightPageEvent - Wait for a page event

Locator Commands

• Assert-PlaywrightLocator - Assert conditions on a locator
• Invoke-PlaywrightLocatorAdvanced - Perform advanced actions on a locator
• Invoke-PlaywrightLocatorClick - Click an element
• Set-PlaywrightLocatorInput - Set input value for an element
• Set-PlaywrightLocatorSelect - Select an option in a dropdown

Prerequisites

Node.js must be installed for PSPlaywright to work. You can download Node.js from nodejs.org. The module uses Playwright, which requires Node.js to run browser automation.

Installation

You can install the PSPlaywright module from the PowerShell Gallery:

Install-Module -Name 'PSPlaywright'

After importing the module, you must install the Playwright browsers required for automation:

Install-Playwright

This will download and install Chromium, Firefox, and WebKit browsers for Playwright automation.

Examples

Getting Started

Basic Browser Setup

Start a browser session and navigate to a webpage:

# Start Playwright and launch a Chromium browser in headless mode
Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Headless -Enter

# Open a new page and navigate to a URL
Open-PlaywrightPage -Url "https://playwright.dev/"

# Get the page title
$title = Get-PlaywrightPageTitle
Write-Host "Page title: $title"

# Clean up
Exit-PlaywrightBrowser
Stop-Playwright

Interactive Browser Session

Launch a visible browser for debugging and manual interaction:

# Start browser with visible window (non-headless)
Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter

# Open a page and pause for manual inspection
Open-PlaywrightPage -Url "https://example.com"
Suspend-PlaywrightPage  # Opens Playwright Inspector for debugging

# Continue automation after inspection
Exit-PlaywrightBrowser
Stop-Playwright

Web Navigation & Content

Navigate and Interact with Pages

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Headless -Enter

# Open a page
Open-PlaywrightPage -Url "https://www.bing.com"

# Get page content
$content = Get-PlaywrightPageContent
Write-Host "Page HTML length: $($content.Length) characters"

# Take a screenshot
Get-PlaywrightPageScreenshot -Path ".\bing-homepage.png" -FullPage

# Navigate to another page
Open-PlaywrightPageUrl -Url "https://github.com"

# Go back
Invoke-PlaywrightPageNavigation -Action GoBack

# Reload the page
Reset-PlaywrightPage

Exit-PlaywrightBrowser
Stop-Playwright

Set Custom Content

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter

Open-PlaywrightPage -Url "about:blank"

# Set custom HTML content
$html = @"
<!DOCTYPE html>
<html>
<head><title>Test Page</title></head>
<body>
    <h1>Hello from PowerShell!</h1>
    <button id="myButton">Click Me</button>
</body>
</html>
"@

Set-PlaywrightPageContent -Html $html

# Take a screenshot of custom content
Get-PlaywrightPageScreenshot -Path ".\custom-page.png"

Exit-PlaywrightBrowser
Stop-Playwright

Finding & Interacting with Elements

Find Elements Using Different Selectors

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter
Open-PlaywrightPage -Url "https://github.com/login"

# Find by role (accessibility)
$loginButton = Find-PlaywrightPageElement -Role "button" -Name "Sign in"

# Find by label (form fields)
$usernameField = Find-PlaywrightPageElement -Label "Username or email address"

# Find by placeholder text
$searchBox = Find-PlaywrightPageElement -Placeholder "Search GitHub"

# Find by text content
$linkElement = Find-PlaywrightPageElement -Text "Create an account"

# Find by alt text (images)
$logo = Find-PlaywrightPageElement -AltText "GitHub"

Exit-PlaywrightBrowser
Stop-Playwright

Click Elements

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter
Open-PlaywrightPage -Url "https://example.com"

# Find and click a button
$button = Find-PlaywrightPageElement -Role "button" -Name "Submit"
Invoke-PlaywrightLocatorClick -Locator $button

# Click with options (double-click, right-click, etc.)
$element = Find-PlaywrightPageElement -Role "link" -Name "More info"
Invoke-PlaywrightLocatorClick -Locator $element -ClickCount 2  # Double-click

Exit-PlaywrightBrowser
Stop-Playwright

Form Automation

Fill Out and Submit a Form

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter
Open-PlaywrightPage -Url "https://example.com/contact"

# Fill text inputs
$nameField = Find-PlaywrightPageElement -Label "Name"
Set-PlaywrightLocatorInput -Locator $nameField -Value "John Doe"

$emailField = Find-PlaywrightPageElement -Label "Email"
Set-PlaywrightLocatorInput -Locator $emailField -Value "john@example.com"

$messageField = Find-PlaywrightPageElement -Label "Message"
Set-PlaywrightLocatorInput -Locator $messageField -Value "This is a test message from PSPlaywright!"

# Select from dropdown
$countryDropdown = Find-PlaywrightPageElement -Label "Country"
Set-PlaywrightLocatorSelect -Locator $countryDropdown -Value "USA"

# Submit the form
$submitButton = Find-PlaywrightPageElement -Role "button" -Name "Submit"
Invoke-PlaywrightLocatorClick -Locator $submitButton

# Wait for navigation or success message
Start-Sleep -Seconds 2

Exit-PlaywrightBrowser
Stop-Playwright

Assertions & Testing

Verify Element States

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter
Open-PlaywrightPage -Url "https://example.com"

# Assert element is visible
$header = Find-PlaywrightPageElement -Role "heading" -Name "Example Domain"
Assert-PlaywrightLocator -Locator $header -IsVisible

# Assert element contains text
$paragraph = Find-PlaywrightPageElement -Role "paragraph"
Assert-PlaywrightLocator -Locator $paragraph -ContainsText "This domain is for use"

# Assert element is enabled
$button = Find-PlaywrightPageElement -Role "button"
Assert-PlaywrightLocator -Locator $button -IsEnabled

# Assert element count
$links = Find-PlaywrightPageElement -Role "link"
Assert-PlaywrightLocator -Locator $links -Count 1

Exit-PlaywrightBrowser
Stop-Playwright

Advanced Scenarios

Keyboard & Mouse Interactions

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter
Open-PlaywrightPage -Url "https://www.google.com"

# Type text using keyboard
Invoke-PlaywrightPageKeyboard -Action Type -Text "PowerShell automation"

# Press specific keys
Invoke-PlaywrightPageKeyboard -Action Press -Key "Enter"

# Use keyboard shortcuts
Invoke-PlaywrightPageKeyboard -Action Press -Key "Control+A"  # Select all

# Mouse interactions
Invoke-PlaywrightPageMouse -Action Click -X 100 -Y 200
Invoke-PlaywrightPageMouse -Action Move -X 300 -Y 400

Exit-PlaywrightBrowser
Stop-Playwright

Generate PDF from Webpage

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter
Open-PlaywrightPage -Url "https://playwright.dev/"

# Generate PDF with custom options
Get-PlaywrightPagePdf -Path ".\playwright-docs.pdf" -Format "A4" -PrintBackground

Exit-PlaywrightBrowser
Stop-Playwright

Execute JavaScript

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter
Open-PlaywrightPage -Url "https://example.com"

# Execute JavaScript on the page
$result = Invoke-PlaywrightPageJavascript -Script "return document.title;"
Write-Host "Page title from JS: $result"

# Execute more complex JavaScript
$links = Invoke-PlaywrightPageJavascript -Script @"
    return Array.from(document.querySelectorAll('a')).map(a => a.href);
"@
Write-Host "Found $($links.Count) links"

Exit-PlaywrightBrowser
Stop-Playwright

Viewport & Media Emulation

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter
Open-PlaywrightPage -Url "https://example.com"

# Set viewport size (mobile device simulation)
Set-PlaywrightPageViewportSize -Width 375 -Height 667

# Emulate media features
Set-PlaywrightPageMedia -ColorScheme "dark" -ReducedMotion "reduce"

# Take screenshot with mobile viewport
Get-PlaywrightPageScreenshot -Path ".\mobile-view.png"

Exit-PlaywrightBrowser
Stop-Playwright

Wait for Events

Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Enter
Open-PlaywrightPage -Url "https://example.com"

# Click a link and wait for navigation
$link = Find-PlaywrightPageElement -Role "link"
Invoke-PlaywrightLocatorClick -Locator $link

# Wait for a specific event
Wait-PlaywrightPageEvent -Event "load" -Timeout 30000

Exit-PlaywrightBrowser
Stop-Playwright

Multi-Browser Testing

Test Across Different Browsers

Start-Playwright

$browsers = @('Chromium', 'Firefox', 'Webkit')
$results = @()

foreach ($browser in $browsers) {
    Write-Host "Testing with $browser..."
    
    Start-PlaywrightBrowser -BrowserType $browser -Headless -Enter
    Open-PlaywrightPage -Url "https://example.com"
    
    # Perform tests
    $title = Get-PlaywrightPageTitle
    $screenshot = ".\test-$browser.png"
    Get-PlaywrightPageScreenshot -Path $screenshot
    
    $results += [PSCustomObject]@{
        Browser = $browser
        Title = $title
        Screenshot = $screenshot
    }
    
    Exit-PlaywrightBrowser
}

# Display results
$results | Format-Table -AutoSize

Stop-Playwright

Complete Example: Web Scraping

# Scrape article titles from a news website
Start-Playwright
Start-PlaywrightBrowser -BrowserType Chromium -Headless -Enter

Open-PlaywrightPage -Url "https://news.ycombinator.com"

# Wait for content to load
Start-Sleep -Seconds 2

# Execute JavaScript to extract article titles
$titles = Invoke-PlaywrightPageJavascript -Script @"
    return Array.from(document.querySelectorAll('.titleline > a'))
        .map(a => ({
            title: a.textContent,
            url: a.href
        }))
        .slice(0, 10);
"@

# Display results
Write-Host "Top 10 Articles:`n"
$titles | ForEach-Object {
    Write-Host "- $($_.title)"
    Write-Host "  URL: $($_.url)`n"
}

Exit-PlaywrightBrowser
Stop-Playwright

Additional Resources

For detailed information about each command and its parameters, refer to the command documentation links in the Commands section above.

For more information about Playwright capabilities, visit the official Playwright documentation.