morph-preview-pr

name	morph-preview-pr
description	Specialized skill for morph_preview_test_pr with PR-native browser verification, task formulation, and result interpretation guidance.

Morph Preview PR

Specialized skill for morph_preview_test_pr — PR-native browser verification with GitHub context and preview deployments.

Purpose

Guide effective use of morph_preview_test_pr for validating pull request previews using Morph's GitHub SDK and browser automation. This skill focuses on task formulation, environment selection, and result interpretation for PR preview testing.

When to Apply

• Validating PR preview deployments before merge
• Testing UI changes in pull requests
• Verifying feature branches with preview environments
• Running automated browser checks on PRs
• Confirming deployment-specific behavior

Prerequisites

Before using morph_preview_test_pr:

1. GitHub App Installation

   • Morph GitHub App must be installed for the repository
   • Check with /morph_selftest if unsure

2. Preview Deployment

   • PR must have a successful preview deployment
   • Common providers: Vercel, Netlify, Cloudflare Pages, GitHub Pages
   • Deployment must be in "success" state

3. Repository Access

   • You need owner/repo/prNumber information
   • PR must be accessible via GitHub API

Quick Start

Basic Usage

{
  "owner": "acme",
  "repo": "app",
  "prNumber": 42,
  "task": "Focus on the new login form. Test email/password fields, submit button, and error validation."
}

With Environment Selection

{
  "owner": "acme",
  "repo": "app",
  "prNumber": 42,
  "task": "Test the updated checkout flow",
  "preferredEnvironment": "preview"
}

With PR Comment

{
  "owner": "acme",
  "repo": "app",
  "prNumber": 42,
  "task": "Test critical payment integration changes",
  "postComment": true
}

Task Formulation

Good Task Structure

1. Context: What feature/change to focus on
2. Actions: What to do (navigate, click, fill, verify)
3. Validation: What to check for success

Template:

Focus on [feature/change from PR]. 
Navigate to [page/section].
[Action 1], [Action 2], [Action 3].
Verify [success criteria].

Examples by Change Type

New Form:

Focus on the new contact form added in this PR. Navigate to /contact, verify all fields (name, email, message) are present, fill them with valid data, submit the form, and confirm the success message appears.

Updated Component:

Focus on the redesigned navigation bar. Verify the new logo appears, the menu items are correctly aligned, the mobile hamburger menu works, and all links navigate to the correct pages.

Bug Fix:

Focus on the fixed date picker bug. Navigate to /events/create, open the date picker, select a date in the past, and verify the validation error appears as expected (previously it didn't).

Performance Change:

Focus on the optimized image loading. Navigate to /gallery, scroll through the page, and verify images load progressively without layout shift.

API Integration:

Focus on the new payment integration. Navigate to /checkout, select the new payment method, enter test card details, submit, and verify the payment confirmation appears.

Task Quality Checklist

• Specific to PR changes (not generic "test the app")
• Includes navigation steps
• Defines expected outcomes
• Tests both success and error cases
• Mentions visual feedback to verify

Environment Selection

When to Use preferredEnvironment

Use when:

• PR has multiple deployments
• Need to target specific environment type
• Default selection is ambiguous

Common values:

• "preview" — standard preview deployment (most common)
• "staging" — staging environment
• "production" — production deployment (rare for PRs)

Default behavior:

• Tool auto-selects first successful deployment
• Works fine for single-deployment PRs

Check Run vs PR Comment

Check Run Only (Default)

When to use:

• Routine PRs with standard CI checks
• Automated testing workflows
• When check run status is sufficient

Benefits:

• Clean PR thread
• Integrated with CI/CD status
• Automatic updates on re-runs

With PR Comment (postComment: true)

When to use:

• High-visibility PRs
• Complex UI changes needing video preview
• Reviewers not checking CI status regularly
• Test results need discussion

Benefits:

• More visible to reviewers
• Recording preview in comment
• Easier to discuss specific issues

Retry Strategies

When to Retry

Deployment not ready:

• Wait 30-60 seconds
• Check deployment status
• Retry with same task

Task too vague:

• Refine task to be more specific
• Add explicit navigation steps
• Include expected outcomes

Timing issues:

• Add wait steps in task
• Increase implicit wait expectations
• Mention loading states to wait for

Network issues:

• Retry immediately (transient)
• Check deployment health
• Verify preview URL is accessible

When NOT to Retry

Consistent failures:

• Recording shows actual bugs
• Console errors indicate real issues
• Behavior differs from expectations → Investigate and fix the bug

Wrong test approach:

• Task tests wrong feature
• Environment selection incorrect
• Prerequisites not met → Adjust approach, don't retry blindly

Handling Flaky Tests

Identify Flaky Tests

Signs:

• Passes sometimes, fails other times
• Timing-dependent failures
• Network-dependent failures
• Animation/transition issues

Mitigation Strategies

1. Add explicit waits:

Wait for loading spinner to disappear before clicking submit.

2. Verify state before action:

Verify the modal is fully open before clicking the confirm button.

3. Test in sequence:

First verify element is visible, then verify it's clickable, then click.

4. Avoid race conditions:

Wait for API response to complete before checking updated data.

5. Handle animations:

Wait for slide-in animation to finish before interacting with sidebar.

Flaky Test Report

When a test is flaky:

1. Document the flakiness in PR comment
2. Suggest adding explicit waits in code
3. Recommend retry with adjusted task
4. Consider if test is too timing-sensitive

Execution Patterns

Pattern 1: Standard PR Validation

1. Identify PR (owner/repo/prNumber)
2. Read PR description/diff
3. Formulate focused task
4. Run morph_preview_test_pr
5. Review check run
6. Address failures

Pattern 2: Multi-Environment PR

1. Identify PR with multiple deployments
2. Determine target environment
3. Run with preferredEnvironment
4. Validate environment-specific behavior
5. Optionally test other environments

Pattern 3: High-Visibility PR

1. Identify critical PR
2. Read changes thoroughly
3. Formulate comprehensive task
4. Run with postComment: true
5. Review recording
6. Discuss in PR thread

Pattern 4: Iterative Testing

1. Run initial test
2. Review recording
3. Identify issues
4. Refine task
5. Run again
6. Compare results

Pattern 5: Flaky Test Recovery

1. Test fails unexpectedly
2. Review recording for timing issues
3. Adjust task with explicit waits
4. Retry with refined task
5. Document flakiness if persists

CI/CD Integration

Automated PR Testing

Trigger on:

• PR opened
• PR updated (new commits)
• Deployment succeeded

Workflow:

# Example GitHub Actions
on:
  pull_request:
    types: [opened, synchronize]
  deployment_status:

jobs:
  test-preview:
    if: github.event.deployment_status.state == 'success'
    steps:
      - name: Test PR Preview
        run: |
          pi -c "Use morph-preview-pr skill to test PR #${{ github.event.pull_request.number }}"

Best Practices for CI

• ✅ Wait for deployment success before testing
• ✅ Use check runs (not comments) for automated tests
• ✅ Set reasonable timeout (2-3 minutes)
• ✅ Retry once on failure (handle transient issues)
• ✅ Post comment only on persistent failures

Interpreting Results

Success Indicators

• ✅ Check run status: "success"
• ✅ Summary describes expected behavior
• ✅ Recording shows correct UI state
• ✅ No console errors
• ✅ All validation steps passed

Failure Indicators

• ❌ Check run status: "failure"
• ❌ Summary describes errors
• ❌ Recording shows broken UI
• ❌ Console errors visible
• ❌ Validation steps failed

Severity Assessment

Critical (Block merge):

• Core functionality broken
• Security issues visible
• Data loss possible
• Complete feature failure

High (Fix before merge):

• Important features broken
• Poor user experience
• Console errors present
• Partial feature failure

Medium (Fix soon):

• Minor UI issues
• Non-critical features broken
• Performance degradation
• Cosmetic problems

Low (Nice to fix):

• Minor cosmetic issues
• Edge case failures
• Non-blocking warnings

Common Mistakes

❌ Don't

• Use generic tasks like "test the app"
• Test unrelated functionality
• Skip reading PR context
• Use for non-PR URLs (use morph_browser_test_url)
• Assume deployment is ready
• Post comments on every PR
• Test before deployment succeeds
• Retry blindly without adjusting task

✅ Do

• Read PR diff/description first
• Focus on specific PR changes
• Use clear, actionable tasks
• Specify preferredEnvironment when needed
• Use postComment for high-visibility PRs
• Review recording on failures
• Adjust task based on results
• Verify deployment status first
• Handle flaky tests appropriately

Multi-Page Flow Testing

Complex User Journeys

Example: Checkout flow

Focus on the updated checkout flow in this PR.
1. Navigate to /products, add item to cart
2. Click cart icon, verify item appears
3. Click 'Checkout', verify redirect to /checkout
4. Fill shipping form (name, address, city, zip)
5. Click 'Continue to Payment'
6. Verify payment form appears with new payment method selector
7. Select new payment method, verify form updates
8. Fill test card details
9. Click 'Place Order'
10. Verify order confirmation page with order number

Tips for multi-page flows:

• Number steps clearly
• Verify each transition
• Include expected outcomes per step
• Test data persistence across pages
• Verify back button behavior

Integration with Other Skills

With morph-power-user

• Use WarpGrep to understand PR changes
• Read changed files before formulating task
• Use FastApply to fix issues found

With morph-reviewer

• Review test results for quality
• Validate task matched PR changes
• Assess failure severity
• Determine if failures are bugs or test issues

With morph-production-tester

• Use similar task formulation patterns
• Apply code analysis techniques
• Cross-reference with codebase

Configuration Awareness

This skill assumes:

• previewPrEnabled: true in Morph config
• previewBrowserTimeoutMs: 120000 (2 minutes) for recording
• Morph GitHub App installed for repository

Check with /morph_status if tool is unavailable.

Success Metrics

• Task focused on PR changes: ✓
• Clear, actionable task description: ✓
• Appropriate environment selected: ✓
• Check run vs comment choice justified: ✓
• Results interpreted correctly: ✓
• Recording reviewed on failures: ✓
• Retries used appropriately: ✓
• Flaky tests handled properly: ✓
• Severity assessed accurately: ✓