test: add example-build-artifacts workflow (#1456)

* test: add example-build-artifacts workflow

* add wait-on parameter

* add reference to matrix strategy with parallel jobs

Author: MikeMcC399

.github/workflows/example-build-artifacts.yml

@@ -0,0 +1,59 @@
+name: example-build-artifacts
+# This workflow shows how to split build and test steps with artifacts.
+# In the build job, dependencies are installed, the app is built and the build results
+# are stored as an artifact using actions/upload-artifact.
+# No tests are run in the build job.
+# The test jobs use the results from the build job:
+# - dependencies and the Cypress binary are installed using dependency caching
+# - build results are restored using actions/download-artifact
+on:
+  push:
+    branches:
+      - 'master'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build app
+        uses: ./ # refers to local instance of cypress-io/github-action@v6
+        with:
+          runTests: false # only build app, don't test yet
+          build: npm run build
+          working-directory: examples/nextjs
+      - name: Store build artifacts
+        uses: actions/upload-artifact@v4 # https://github.com/actions/upload-artifact
+        with:
+          name: app
+          path: examples/nextjs/build
+          if-no-files-found: error
+          retention-days: 1
+
+  test:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, windows-2025, macos-15]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Restore build artifacts
+        uses: actions/download-artifact@v4 # https://github.com/actions/download-artifact
+        with:
+          name: app
+          path: examples/nextjs/build
+
+      - name: Cypress tests
+        uses: ./
+        with:
+          start: npm start # start server using the build artifacts
+          wait-on: http://localhost:3000
+          working-directory: examples/nextjs

README.md

@@ -70,6 +70,7 @@ The following examples demonstrate the actions' functions.
 - Use [custom cache key](#custom-cache-key)
 - Run tests on multiple [Node versions](#node-versions)
 - Split [install and tests](#split-install-and-tests) into separate jobs
+- Split [install and tests](#split-install-and-test-with-artifacts) with artifacts
 - Use [custom install commands](#custom-install)
 - Install [only Cypress](#install-cypress-only) to avoid installing all dependencies
 - Use [timeouts](#timeouts) to avoid hanging CI jobs
@@ -1386,6 +1387,54 @@ jobs:
 
 See [cypress-gh-action-monorepo](https://github.com/bahmutov/cypress-gh-action-monorepo) for a working example.
 
+### Split install and test with artifacts
+
+If your test job(s) first need a build step, you can split the jobs into a separate build job followed by test jobs. You pass the build results to any subsequent jobs using [GitHub Actions artifacts](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow).
+
+In the build job, use [upload-artifact](https://github.com/actions/upload-artifact) to store the build results, then in subsequent jobs use [download-artifact](https://github.com/actions/download-artifact) to restore them.
+
+Your tests jobs may use a [GitHub Actions matrix strategy](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow), such as when recording to [Cypress Cloud](https://on.cypress.io/cloud-introduction) with [parallel jobs](#parallel).
+
+```yml
+name: Split build and test
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build app
+        uses: cypress-io/github-action@v6
+        with:
+          runTests: false # only build app, don't test yet
+          build: npm run build
+      - name: Store build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: app
+          path: build
+          if-no-files-found: error
+          retention-days: 1
+
+  test:
+    needs: build
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Restore build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: app
+          path: build
+
+      - name: Cypress tests
+        uses: cypress-io/github-action@v6
+        with:
+          start: npm start # start server using the build artifacts
+```
+
+[![Split with build artifacts](https://github.com/cypress-io/github-action/actions/workflows/example-build-artifacts.yml/badge.svg)](.github/workflows/example-build-artifacts.yml)
+
 ### Custom install
 
 Finally, you might not need this GH Action at all. For example, if you want to split the npm dependencies installation from the Cypress binary installation, then it makes no sense to use this action. Instead you can install and cache Cypress yourself.

examples/nextjs/next.config.mjs

@@ -1,4 +1,6 @@
 /** @type {import('next').NextConfig} */
-const nextConfig = {};
+const nextConfig = {
+  distDir: 'build',
+};
 
 export default nextConfig;