How to Run End-to-End Tests on Vercel Preview Deployments

End-to-end (E2E) tests are an essential part of modern web development. They simulate real user interactions and ensure your application works as expected in a live environment. When you're working with platforms like Vercel, which provide seamless deployment experiences, running E2E tests on preview deployments makes sense to catch any issues before merging your changes into the main branch.

However, running E2E tests on preview deployments can be challenging as if the deployment isn’t ready when the tests start running, you’ll get errors when they should have succeeded.

The Challenge: Timing Your E2E Tests

Imagine you're working on a feature and pushing your changes to a branch. Vercel starts deploying the preview, and once that's done, you want to run your E2E tests automatically. But if the deployment isn't ready when the tests start, they might fail, and you'll be left wondering if the issue is with your code or the deployment process.

Github Actions allow us to leverage a combination of actions that work together to ensure that your E2E tests only start once the Vercel deployment is ready.

The Solution: Combining GitHub Actions for Seamless Testing

To solve this problem, we can use two GitHub Actions in tandem:

1. vercel-preview-url: This action retrieves the preview URL of the Vercel deployment. It runs on push and pull request events, ensuring you get the exact URL of your deployment, which can then be used for further tests or other integrations.

2. github-action-await-vercel: This action waits until the Vercel deployment is marked as "READY". It continuously checks the deployment status, ensuring your tests only run once the deployment is fully prepared.
   

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      # Step 1: Retrieve the Vercel Preview URL
      - name: vercel-preview-url
        uses: zentered/vercel-preview-url@v1.1.9
        if: github.event_name != 'pull_request'
        id: vercel_preview_url
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
          GITHUB_REF: "main"
          GITHUB_REPOSITORY: "your-repo/your-project"
        with:
          vercel_project_id: ${{ secrets.VERCEL_PROJECT_ID }}

      # Step 2: Wait for the Vercel deployment to be ready
      - uses: UnlyEd/github-action-await-vercel@v1
        id: await-vercel
        if: github.event_name != 'pull_request'
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        with:
          deployment-url: ${{ steps.vercel_preview_url.outputs.preview_url }}
          timeout: 420
          poll-interval: 15

      # Step 3: Run your end-to-end tests
      - name: Run E2E Tests
        run: npm run test:e2e

Breaking Down the Workflow

1. Fetch the Preview URL: The vercel-preview-url action first retrieves the URL of the Vercel deployment. This URL is unique to the deployment, and we need to know it to run our E2E tests against the correct environment. This step ensures that we have the right URL before proceeding to the next steps.

2. Await Deployment Readiness: The github-action-await-vercel action waits for the deployment to be fully ready. It checks the deployment status at intervals (e.g., every 15 seconds) and only proceeds once the deployment is marked as "READY." This step ensures that your E2E tests don't run prematurely, preventing false failures.

3. Run E2E Tests: Once the deployment is ready, your E2E tests are executed against the live preview. By this point, you can be confident that the environment is fully set up, and any failures will likely be due to actual issues in the code rather than deployment timing.

Why This Workflow Matters

This workflow is essential for teams that rely on automated testing as part of their CI/CD pipelines. By waiting for the Vercel deployment to be fully ready, you minimize the risk of flaky tests that fail due to timing issues rather than code problems. This approach saves time and effort, as developers can focus on fixing real bugs rather than troubleshooting deployment issues.

Moreover, this setup is flexible and can be adapted to various project needs. Whether you're running tests on a simple static site or a complex application, ensuring that your deployment is ready before running tests can dramatically improve the reliability of your CI/CD pipeline.

Conclusion

In modern web development, ensuring the reliability of your CI/CD pipeline is crucial. By leveraging GitHub Actions like vercel-preview-url and github-action-await-vercel, you can confidently run E2E tests on Vercel preview deployments.

However, remember that the Vercel deployment can take some time to deploy, especially for larger projects, so use this approach wisely and ensure you only run it when necessary.