screenshot-automation

Screenshot Automation Guide

This guide provides reusable AppleScript patterns for taking automated screenshots of applications, particularly useful for documentation, testing, and visual verification.

Core Concepts

Application Identification

Applications can be identified through multiple methods:

• Bundle ID: Most reliable for packaged apps (e.g., com.company.AppName)
• Process Name: May differ from app name (e.g., "Electron" for dev builds)
• Absolute Path: Most reliable for development builds and non-standard locations

Basic Screenshot Script

-- Script to take an unattended screenshot of an app window
-- Set appPath to the full path of the application

try
    -- Set this to the full path of the application
    set appPath to "/Applications/YourApp.app"
    
    -- Generate timestamp for unique filename
    set currentDate to do shell script "date '+%Y-%m-%d_%H-%M-%S'"
    set desktopPath to (path to desktop folder as text)
    set posixDesktopPath to POSIX path of desktopPath
    set screenshotPath to posixDesktopPath & "app_screenshot_" & currentDate & ".png"
    
    -- Extract app name from path
    set appName to do shell script "basename " & quoted form of appPath & " .app"
    
    -- Check if app is running and get process name
    set isRunning to false
    set appProcessName to ""
    
    -- Try to identify by bundle ID first
    try
        set appBundleID to do shell script "mdls -name kMDItemCFBundleIdentifier -raw " & quoted form of appPath
        
        tell application "System Events"
            set allProcesses to every process
            repeat with currentProcess in allProcesses
                try
                    if bundle identifier of currentProcess is appBundleID then
                        set isRunning to true
                        set appProcessName to name of currentProcess
                        exit repeat
                    end if
                end try
            end repeat
        end tell
    on error
        -- Fallback to app name matching
        set appProcessName to appName
        tell application "System Events"
            if exists process appProcessName then
                set isRunning to true
            end if
        end tell
    end try
    
    -- Launch app if not running
    if not isRunning then
        do shell script "open " & quoted form of appPath
        delay 2 -- Wait for app to launch
        
        -- Identify the launched process
        tell application "System Events"
            set newProcesses to every process
            repeat with currentProcess in newProcesses
                try
                    set processName to name of currentProcess
                    if processName contains appName then
                        set appProcessName to processName
                        set isRunning to true
                        exit repeat
                    end if
                end try
            end repeat
        end tell
    end if
    
    -- Verify we have a valid process
    if appProcessName is "" or not isRunning then
        return "Could not determine process name for app at path: " & appPath
    end if
    
    -- Take the screenshot
    tell application "System Events"
        tell process appProcessName
            -- Bring to front
            try
                set frontmost to true
                delay 0.5 -- Allow time to come to front
            on error errMsg
                log "Note: Could not bring " & appProcessName & " to front: " & errMsg
            end try
            
            if (count of windows) > 0 then
                set appWindow to window 1
                set windowPosition to position of appWindow
                set windowSize to size of appWindow
                
                set windowX to item 1 of windowPosition
                set windowY to item 2 of windowPosition
                set windowWidth to item 1 of windowSize
                set windowHeight to item 2 of windowSize
                
                -- Validate dimensions
                if windowWidth is 0 or windowHeight is 0 then
                    return "Window has zero dimensions"
                end if
                
                delay 0.5 -- Final delay for window readiness
                set regionString to windowX & "," & windowY & "," & windowWidth & "," & windowHeight
                do shell script "screencapture -x -R" & regionString & " " & quoted form of screenshotPath
                
                return "Screenshot saved to: " & screenshotPath
            else
                return "No windows found for " & appProcessName
            end if
        end tell
    end tell
on error errMsg
    return "Error: " & errMsg
end try