blog: improve vercel preview article

Author: jsfez

articles/vercel-preview/index.mdx

@@ -1,37 +1,116 @@
 ---
-title: How to run Argos visual testing on Vercel Preview
-description: Guide to run Argos visual testing on Vercel Preview to ensure consistency in production-like environment.
-slug: vercel-preview
+title: "Guide: Integrating Argos Visual Testing in Vercel Preview"
+description: "A guide to setting up Argos integration with Vercel Preview using GitHub Actions."
 category: Developer Experience
 author: Jeremy Sfez
 date: 2024-02-01
 image: ./main.jpg
 imageAlt: Vercel covered with Argos
 ---
 
-Great news for Vercel enthusiasts! Argos seamlessly integrates visual testing with Vercel Preview, enabling you to detect visual regressions in a production-like environment effortlessly. This guide walks you through setting it up with GitHub Actions and Playwright, streamlining your workflow.
+Argos now seamlessly integrates integrates with Vercel Preview for visual testing, offering a streamlined approach to catch visual regressions in a production-like environment — without the hassle of complex setups. his guide will walk you through implementing Argos with Vercel Preview via GitHub Actions, complete with source code insights.
 
 <MainImage />
 
-## Motivation behind this feature
+## Why Visual Testing with Vercel Preview? Key Advantages
 
-Responding to user feedback, we recognized the need for visual testing directly on Vercel Previews, especially for environments akin to production settings. This approach is not only cost-effective, eliminating the need for separate test environments, but also enhances test accuracy by mirroring production conditions closely.
+- **Direct Visual Verification:** Allows for immediate identification of visual changes in pull requests, ensuring what you see is what you get in production.
+- **Cost Reduction:** Reduces CI expenses by eliminating the need to duplicate test environments.
+- **Production-like Environment Testing:** Offers a closer approximation to the live site, increasing test reliability.
 
-## How to run Argos on Vercel Preview
+**Note:** This method is optimal for repeatable tests that don't significantly alter the environment, as certain tests (e.g. those involving user deletion) may not be applicable.
 
-### 1. Set up Argos
+## Getting Started with Argos: Setup Guide
 
-Start by following the Q[Quickstart guide](https://argos-ci.com/docs) to integrate Argos with Playwright. This foundational step ensures that Argos is ready to run visual tests during your CI process.
+### Prerequisites
 
-### 2. Run tests on your Vercel Preview
+Before integrating Argos into Vercel Preview for visual testing, I ensured:
 
-Adapt your CI workflow with this GitHub Actions configuration to enable Argos visual testing on Vercel Previews:
+1. Set up a [Next.js](https://nextjs.org/) project with [Playwright](https://playwright.dev).
+2. Integrated Playwright tests into CI/CD.
+3. Deployed the project on Vercel.
+
+### 1. Project Importation to Argos
+
+I [signed up into Argos](https://app.argos-ci.com/signup) and imported my project. Once done, Argos display an `ARGOS_TOKEN` for this repository. I saved it for the next step.
+
+I [signed up into Argos](https://app.argos-ci.com/signup) on Argos and added my project. After this, Argos generated an `ARGOS_TOKEN` for my repository. I saved it for later.
+
+![Argos GitHub token](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wra1891953mfv4kt6tcs.png)
+
+### 2. Package Installation
+
+```sh
+npm install --save-dev @argos-ci/playwright
+```
+
+### 3. Setup Argos in Playwright config file
+
+Update the `playwright.config.ts` file:
+
+```ts
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  reporter: [
+    process.env.CI ? ["dot"] : ["list"],
+    [
+      "@argos-ci/playwright/reporter",
+      {
+        uploadToArgos: !!process.env.CI,
+        token: process.env.ARGOS_TOKEN,
+      },
+    ],
+  ],
+  use: {
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+  },
+});
+```
+
+### 4. Screenshot my app
+
+I utilized the [Screenshot pages script](https://argos-ci.com/docs/screenshot-pages-script) from Argos's documentation for capturing my application's homepage. This script is flexible for adding more pages in the future.
+
+```ts
+import { argosScreenshot } from "@argos-ci/playwright";
+import { test } from "@playwright/test";
+
+const baseUrl = "http://localhost:3000";
+const pages = [
+  { name: "homepage", path: "/" },
+  // { name: "faq", path: "/faq" },
+  // { name: "contact", path: "/contact-us" },
+  // { name: "pricing", path: "/pricing" },
+];
+
+test("screenshot pages", async ({ page }, workerInfo) => {
+  for (const { name, path } of pages) {
+    const browserName = workerInfo.project.name;
+    await page.goto(`${baseUrl}${path}`);
+    await argosScreenshot(page, `${name}-${browserName}`);
+  }
+});
+```
+
+### 5. Set up ARGOS_TOKEN and test integration
+
+First, I set up `ARGOS_TOKEN` as a repository secret on GitHub. Then, I pushed my branch to Github and monitored the status checks to ensure everything was functioning as expected: Playwright, Vercel, and Argos.
+
+![Github tests with Argos](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/om5itnow41f3koolbwio.png)
+
+## Run Argos on Vercel Preview
+
+To run my tests on Vercel Preview, I updated my CI workflow file:
 
 ```yml
 name: Playwright + Argos Tests
+# 👉 Trigger on deployment event
 on: deployment_status:
 jobs:
   test:
+    # 👉 Run tests only if the deployment is successful
     if: github.event_name == 'deployment_status' && github.event.deployment_status.state == 'success'
     runs-on: ubuntu-latest
     steps:
@@ -41,33 +120,44 @@ jobs:
         run: npm ci && npx playwright install --with-deps
       - name: Run Playwright tests
         run: npx playwright test
+        # 👉 Add this variables
         env:
           BASE_URL: ${{ github.event.deployment_status.environment_url }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ARGOS_BRANCH: ${{ github.event.deployment_status.environment == 'Production' && 'main' || '' }}
 ```
 
-For a comprehensive explanation of each step, consult the [Argos documentation](https://argos-ci.com/docs/run-on-preview-deployment).
+For a comprehensive explanation of each step, read [Argos documentation](https://argos-ci.com/docs/run-on-preview-deployment).
 
-Next, update your Playwright config file is updated to reflect the preview's URL and configure it to ignore the Vercel toolbar for cleaner test results:
+Then, I updated my Playwright's config file:
 
 ```ts
 export default defineConfig({
   use: {
-    # 👉 URL generated for the preview
+    // URL generated for the preview
     baseURL: process.env.BASE_URL,
   },
   extraHTTPHeaders: {
-     # 👉 Hide vercel toolbar in tests
+    // Hide vercel toolbar in tests
     "x-vercel-skip-toolbar": "0",
   },
 });
 ```
 
-Assuming you have automatic deploys set up, you’ll see the results of your deploy in your pull request. Upon a successful deploy, the E2E workflow will start on the preview.
+After this my are merged, upon a successful deploy, the E2E workflow start on the preview:
 
 ![Github pull-request check statuses](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y0zu0bwdykzsu9bvfgzw.png)
 
+## Explore the Source Code
+
+![Github pull-request check statuses](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qhp02ieazr6f38o8q915.png)
+
+Explore my GitHub for a detailed guide on integrating Argos with Vercel Preview, particularly highlighted in Pull Request #2 and the live Vercel deployment:
+
+- [Github Repository](https://github.com/jsfez/argos-vercel-preview)
+- [Pull Request #2 - test: run argos on vercel preview](https://github.com/jsfez/argos-vercel-preview/pull/2)
+- [Deployed Project](https://argos-vercel-preview-gimral7da-jeremy-smooth-code.vercel.app/)
+
 ## Conclusion
 
-Leveraging Argos with Vercel Previews not only enhances visual consistency in a near-production environment but also optimizes your CI process by eliminating the need for additional environments for testing. This integration streamlines your workflow, ensuring that your projects meet the highest standards of visual quality while being cost-effective.
+Integrating Argos and Vercel Preview offers a practical solution for improving visual testing in CI workflows. This setup simplifies identifying visual changes, ensuring your projects look as intended before going live. By following this guide, you're equipped to implement an effective visual testing strategy that minimizes errors and enhances the reliability of your deployments, all within the familiar environment of your existing CI/CD pipeline.