Recording Tests with CLI

​

Recording with the CLI runner

​

Setting up for recording

​

Start the recording tunnel

# Start runner in proxy mode for recording
keystone start --proxy --api-key your-api-key

• Control your local browser
• Access localhost and private networks
• Record interactions with development environments
• Capture network requests and responses

​

Verify recording readiness

# Check runner health and capabilities
curl http://localhost:9223/health

{
  "status": "healthy",
  "capabilities": ["recording", "execution", "screenshots"],
  "proxy": true,
  "connected": true
}

​

Recording workflow

​

1. Start your application

# Start your development server
npm run dev
# Application running on http://localhost:3000

​

2. Configure Keystone Studio

1. Go to Keystone Studio
2. Create a new test
3. Set environment to “Local Development”
4. Verify tunnel connection shows green status
5. Set base URL to http://localhost:3000

​

3. Begin recording

• Browser opens: Studio controls your local browser via the tunnel
• Navigate to localhost: Go to your local application
• Interact naturally: Click, type, navigate as a user would
• AI captures intelligently: Smart selectors and timing automatically recorded

​

4. Complete and save

• Click “Stop Recording” in Studio
• Review captured steps and add descriptions
• Test playback to verify recording quality
• Save to your cloud test library

​

Recording capabilities

​

What gets captured

• Clicks on buttons, links, and elements
• Text input in forms and fields
• Keyboard shortcuts and navigation
• Mouse movements and hover actions
• Scroll positions and viewport changes

• Loading states and animations
• AJAX requests and responses
• Modal dialogs and popups
• Form validation and error messages
• Real-time content updates

• API calls to your local backend
• Authentication flows and token handling
• File uploads and downloads
• WebSocket connections
• External service integrations

​

Smart recording features

• Chooses most stable element identifiers
• Avoids fragile CSS classes and IDs
• Uses semantic attributes when available
• Falls back gracefully when elements change

• Automatically detects loading states
• Waits for dynamic content to appear
• Handles asynchronous operations
• Adapts to variable response times

• Understands form flows and multi-step processes
• Recognizes authentication requirements
• Detects error states and recovery paths
• Captures conditional logic and branching

​

Advanced recording scenarios

​

Recording with authentication

# Set up authenticated session
# 1. Start runner
keystone start --proxy --api-key your-api-key

# 2. Log in manually in Studio-controlled browser
# 3. Authentication state is preserved for recording
# 4. Record authenticated user flows

​

Recording API interactions

# Start backend API server
npm run dev:api

# Start frontend
npm run dev

# Start recording tunnel
keystone start --proxy

# Record tests that interact with local API
# - API calls are captured automatically
# - Responses are recorded for future stubbing
# - Authentication headers are preserved

​

Recording with test data

# Set up test database
npm run db:seed:test

# Start application with test data
npm run dev

# Record against consistent test data
# - Reproducible test scenarios
# - Known user accounts and content
# - Predictable application state

​

Recording error scenarios

# Simulate error conditions
# - Network failures (disconnect WiFi)
# - Server errors (stop backend)
# - Invalid inputs (malformed data)
# - Timeout scenarios (slow responses)

# Record recovery and error handling
# - User sees appropriate error messages
# - Application degrades gracefully
# - Recovery actions work correctly

​

Recording best practices

​

Environment setup

• Start with fresh browser session
• Clear cache and cookies if needed
• Reset application to known state
• Use consistent test data

• Ensure stable internet connection
• Avoid network throttling during recording
• Test on same network as development
• Consider VPN impacts on recording

​

Recording technique

• Interact as a real user would
• Don’t rush through flows
• Let pages load completely
• Use realistic data and inputs

• Record complete user journeys
• Include setup and teardown steps
• Handle expected variations
• Test both success and failure paths

​

Post-recording optimization

• Check recorded steps for accuracy
• Add meaningful descriptions
• Remove unnecessary steps
• Optimize waiting strategies

• Run recorded test to verify functionality
• Test in different environments
• Validate with different data sets
• Ensure reliable reproduction

​

Recording limitations

​

Same-origin restrictions

• localhost applications
• Private network resources
• Development environments
• Applications on same domain

• External sites require proxy mode
• Third-party integrations need special handling
• OAuth redirects may need configuration
• CDN resources should be accessible

​

Session management

• Single browser session at a time
• No concurrent recording sessions
• Session state tied to browser instance
• Manual session cleanup required

• Multi-session support
• Session isolation
• Automatic cleanup
• Concurrent recording capabilities

​

Troubleshooting recording

​

Connection issues

# Verify tunnel connection
curl http://localhost:9223/health

# Check proxy status
keystone start --proxy --debug

​

Browser problems

# Reset browser state
# - Clear cache and cookies
# - Restart browser
# - Check Chrome version compatibility

# Debug browser launch
keystone start --proxy --debug

​

Recording failures

• Network timeouts during recording
• Element selection failures
• Authentication state loss
• Browser crashes or hangs

• Restart runner and try again
• Check application logs for errors
• Verify network connectivity
• Update Chrome browser if needed

​

Performance optimization

# Reduce recording overhead
keystone start --proxy --fast-mode

# Limit capture features
keystone start --proxy --no-screenshots

# Use headless mode for non-visual recording
keystone start --proxy --headless

​

Local vs cloud recording

​

Local recording benefits

• Access to localhost and private networks
• Real browser with full dev tools
• Local file system access
• No network latency

• Test against current branch
• Debug with local tools
• Iterate quickly on changes
• Access to source code

​

Cloud recording benefits

• Shared test library
• Consistent environments
• No local setup required
• Scalable execution

• Managed browser environments
• Automatic updates
• Global accessibility
• High availability

​

Next steps