From 8a8d5eb4b1b6ff7443c66f5b4ce262d6fc49c380 Mon Sep 17 00:00:00 2001 From: Walter Galvao Date: Wed, 18 Mar 2026 02:25:33 -0300 Subject: [PATCH] fix: readme --- cypress/aws-codebuild/README.md | 69 +---- cypress/aws-codebuild/README.upstream.md | 15 -- cypress/aws-codebuild/source__README.md | 15 -- cypress/azure-devops/README.md | 67 +---- cypress/azure-devops/README.upstream.md | 3 - cypress/azure-devops/source__README.md | 3 - cypress/circleci/README.md | 245 +++++++++++++----- cypress/circleci/README.upstream.md | 180 ------------- cypress/circleci/source__README.md | 180 ------------- cypress/cucumber/README.md | 76 +----- cypress/cucumber/README.upstream.md | 14 - cypress/cucumber/source__README.md | 14 - cypress/github-actions/README.md | 123 ++------- cypress/github-actions/README.upstream.md | 44 ---- cypress/github-actions/source__README.md | 44 ---- cypress/netlify/README.md | 209 +++++++++++---- cypress/netlify/README.upstream.md | 182 ------------- cypress/netlify/source__README.md | 182 ------------- cypress/nx/README.md | 98 +++---- cypress/nx/README.upstream.md | 67 ----- cypress/nx/source__README.md | 67 ----- .../jest/github-actions/README.md | 70 ++--- .../jest/github-actions/README.upstream.md | 25 -- .../jest/github-actions/source__README.md | 25 -- generic-reporter/junit/junit-xml/README.md | 83 +----- .../junit/junit-xml/README.upstream.md | 19 -- .../junit/junit-xml/source__README.md | 19 -- .../junit/nodejs-github-actions/README.md | 69 ++--- .../nodejs-github-actions/README.upstream.md | 28 -- .../nodejs-github-actions/source__README.md | 28 -- playwright/bdd-cucumber/README.md | 117 +++++---- playwright/bdd-cucumber/README.upstream.md | 83 ------ playwright/bdd-cucumber/source__README.md | 83 ------ playwright/ci/aws-codebuild/README.md | 183 ++++++++----- .../ci/aws-codebuild/README.upstream.md | 118 --------- playwright/ci/aws-codebuild/source__README.md | 118 --------- playwright/ci/azure-devops/README.md | 82 +++--- playwright/ci/azure-devops/README.upstream.md | 45 ---- playwright/ci/azure-devops/source__README.md | 45 ---- playwright/ci/circleci/README.md | 61 +---- playwright/ci/circleci/README.upstream.md | 13 - playwright/ci/circleci/source__README.md | 13 - .../ci/jenkins/jenkins-last-failed/README.md | 85 +----- .../jenkins-last-failed/README.upstream.md | 18 -- .../jenkins-last-failed/source__README.md | 18 -- playwright/ci/nx/README.md | 159 +++++++----- playwright/ci/nx/README.upstream.md | 116 --------- playwright/ci/nx/source__README.md | 116 --------- .../instrumented-coverage/README.md | 80 ++---- .../instrumented-coverage/README.upstream.md | 26 -- .../instrumented-coverage/source__README.md | 26 -- playwright/component-testing/README.md | 111 ++++---- .../component-testing/README.upstream.md | 44 ---- .../component-testing/source__README.md | 44 ---- playwright/orchestration/README.md | 79 ++---- playwright/orchestration/README.upstream.md | 33 --- playwright/orchestration/source__README.md | 33 --- playwright/pnpm/README.md | 72 ++--- playwright/pnpm/README.upstream.md | 30 --- playwright/pnpm/source__README.md | 30 --- 60 files changed, 916 insertions(+), 3428 deletions(-) delete mode 100644 cypress/aws-codebuild/README.upstream.md delete mode 100644 cypress/aws-codebuild/source__README.md delete mode 100644 cypress/azure-devops/README.upstream.md delete mode 100644 cypress/azure-devops/source__README.md delete mode 100644 cypress/circleci/README.upstream.md delete mode 100644 cypress/circleci/source__README.md delete mode 100644 cypress/cucumber/README.upstream.md delete mode 100644 cypress/cucumber/source__README.md delete mode 100644 cypress/github-actions/README.upstream.md delete mode 100644 cypress/github-actions/source__README.md delete mode 100644 cypress/netlify/README.upstream.md delete mode 100644 cypress/netlify/source__README.md delete mode 100644 cypress/nx/README.upstream.md delete mode 100644 cypress/nx/source__README.md delete mode 100644 generic-reporter/jest/github-actions/README.upstream.md delete mode 100644 generic-reporter/jest/github-actions/source__README.md delete mode 100644 generic-reporter/junit/junit-xml/README.upstream.md delete mode 100644 generic-reporter/junit/junit-xml/source__README.md delete mode 100644 generic-reporter/junit/nodejs-github-actions/README.upstream.md delete mode 100644 generic-reporter/junit/nodejs-github-actions/source__README.md delete mode 100644 playwright/bdd-cucumber/README.upstream.md delete mode 100644 playwright/bdd-cucumber/source__README.md delete mode 100644 playwright/ci/aws-codebuild/README.upstream.md delete mode 100644 playwright/ci/aws-codebuild/source__README.md delete mode 100644 playwright/ci/azure-devops/README.upstream.md delete mode 100644 playwright/ci/azure-devops/source__README.md delete mode 100644 playwright/ci/circleci/README.upstream.md delete mode 100644 playwright/ci/circleci/source__README.md delete mode 100644 playwright/ci/jenkins/jenkins-last-failed/README.upstream.md delete mode 100644 playwright/ci/jenkins/jenkins-last-failed/source__README.md delete mode 100644 playwright/ci/nx/README.upstream.md delete mode 100644 playwright/ci/nx/source__README.md delete mode 100644 playwright/code-coverage/instrumented-coverage/README.upstream.md delete mode 100644 playwright/code-coverage/instrumented-coverage/source__README.md delete mode 100644 playwright/component-testing/README.upstream.md delete mode 100644 playwright/component-testing/source__README.md delete mode 100644 playwright/orchestration/README.upstream.md delete mode 100644 playwright/orchestration/source__README.md delete mode 100644 playwright/pnpm/README.upstream.md delete mode 100644 playwright/pnpm/source__README.md diff --git a/cypress/aws-codebuild/README.md b/cypress/aws-codebuild/README.md index a945f15..38e7a26 100644 --- a/cypress/aws-codebuild/README.md +++ b/cypress/aws-codebuild/README.md @@ -1,68 +1,15 @@ -# Cypress reporting on AWS CodeBuild +# Currents.dev - AWS CodeBuild Example -- **Framework:** `cypress` -- **Use case:** `ci/aws-codebuild` -- **Source repository:** https://github.com/currents-dev/aws-codebuild-example +The full guide: https://currents.dev/readme/ci-setup/aws-code-build -## What this example does +This is an example repository that showcases using [Currents.dev](https://currents.dev) for running parallel cypress tests using AWS CodeBuild CI -An example repo showing how to run **Cypress tests in parallel on AWS CodeBuild** and report them to **Currents** using `cypress-cloud`, specifically using CodeBuild **batch build + matrix mode** with **3 workers**. +The example [buildspec.yml](https://github.com/currents-dev/aws-codebuild-example/blob/main/buildspec.yml) defines a configuration for running cypress tests in parallel mode using 3 workers in [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html#batch_build_matrix). The example is designed to be executed within a [batch build](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html). -## How this example is used +- Note: The example uses [CODEBUILD_INITIATOR](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html) as a [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id). When testing interactively, the CODEBUILD_INITIATOR will be set to the username of the build initiator. When running a batched build, the variable will have the batch build id. -1. **Create a Currents project** and obtain: - - `recordKey` (set as CodeBuild env var `CURRENTS_RECORD_KEY`) - - `projectId` (set in `currents.config.js`) -2. **Run on AWS CodeBuild using batch/matrix** - - `buildspec.yml` defines matrix `WORKERS: 1,2,3` and runs `npx cypress-cloud run --record --parallel --ci-build-id $CODEBUILD_INITIATOR`. -3. **Cypress configuration** - - Uses `cloudPlugin` from `cypress-cloud/plugin`, sets `baseUrl` to TodoMVC, and looks for specs in `cypress/e2e/*.spec.js` with support file `cypress/support/e2e.ts`. -4. **CI Build ID behavior** - - README notes it uses `CODEBUILD_INITIATOR` as the CI Build ID, and explains differences between interactive vs batch builds. +- Note: get your record key from [Currents.dev](https://app.currents.dev) and set [AWS CodeBuild Environment Variable](https://docs.aws.amazon.com/codebuild/latest/userguide/change-project-console.html#change-project-console-environment) variable `CURRENTS_RECORD_KEY` -## What scenarios are included +- Note: set the `projectId` in `currents.config.js` - obtain the project id from [Currents.dev](https://app.currents.dev) -- **CodeBuild batch/matrix parallelization** - - `buildspec.yml` with 3 workers and a parallel Cypress Cloud run (`--parallel --record`). -- **Currents project configuration** - - `currents.config.js` with a `projectId` field. -- **Cypress + Currents integration** - - `cypress.config.ts` showing `cloudPlugin(...)`, video settings, baseUrl, and spec pattern. -- **Dependencies** - - `package.json` includes `cypress` + `cypress-cloud` + `typescript`. - -> Note: The repo clearly expects Cypress specs under `cypress/e2e/*.spec.js` but GitHub directory listing for `cypress/` didn’t render in the captured view, so I’m describing the tests based on the config rather than enumerating filenames. - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Reformat files (they’re currently effectively one-liners in raw view)** - - README + `buildspec.yml` + `cypress.config.ts` are hard to scan because they render as long single lines; reformat into normal multiline files. -2. **Add a real “Quickstart”** - - Explicit steps: create Currents project → set `CURRENTS_RECORD_KEY` → set `projectId` → run CodeBuild batch build. - - Include copy/paste commands for local run (even if it’s not CodeBuild). -3. **Add `scripts` in `package.json`** - - Example: `npm run cy:cloud` to run `cypress-cloud run --record --parallel ...` (right now there’s only a placeholder `test` script). -4. **Add `.env.example`** - - Show required env vars and safe handling (avoid pasting keys into shell history). -5. **Make worker count configurable** - - Right now sharding is implicitly “3 workers” via matrix; add a single place to change it (and document it). -6. **Include a sample CodeBuild Project JSON (optional but helpful)** - - Similar to the Playwright CodeBuild example repo which includes a project config output; having that here would reduce AWS console guesswork. - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **25** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +- Note: use CLI arguments to customize your cypress-cloud runs, e.g.: `npx cypress-cloud run --parallel --record --key --group groupA` diff --git a/cypress/aws-codebuild/README.upstream.md b/cypress/aws-codebuild/README.upstream.md deleted file mode 100644 index 38e7a26..0000000 --- a/cypress/aws-codebuild/README.upstream.md +++ /dev/null @@ -1,15 +0,0 @@ -# Currents.dev - AWS CodeBuild Example - -The full guide: https://currents.dev/readme/ci-setup/aws-code-build - -This is an example repository that showcases using [Currents.dev](https://currents.dev) for running parallel cypress tests using AWS CodeBuild CI - -The example [buildspec.yml](https://github.com/currents-dev/aws-codebuild-example/blob/main/buildspec.yml) defines a configuration for running cypress tests in parallel mode using 3 workers in [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html#batch_build_matrix). The example is designed to be executed within a [batch build](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html). - -- Note: The example uses [CODEBUILD_INITIATOR](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html) as a [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id). When testing interactively, the CODEBUILD_INITIATOR will be set to the username of the build initiator. When running a batched build, the variable will have the batch build id. - -- Note: get your record key from [Currents.dev](https://app.currents.dev) and set [AWS CodeBuild Environment Variable](https://docs.aws.amazon.com/codebuild/latest/userguide/change-project-console.html#change-project-console-environment) variable `CURRENTS_RECORD_KEY` - -- Note: set the `projectId` in `currents.config.js` - obtain the project id from [Currents.dev](https://app.currents.dev) - -- Note: use CLI arguments to customize your cypress-cloud runs, e.g.: `npx cypress-cloud run --parallel --record --key --group groupA` diff --git a/cypress/aws-codebuild/source__README.md b/cypress/aws-codebuild/source__README.md deleted file mode 100644 index 38e7a26..0000000 --- a/cypress/aws-codebuild/source__README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Currents.dev - AWS CodeBuild Example - -The full guide: https://currents.dev/readme/ci-setup/aws-code-build - -This is an example repository that showcases using [Currents.dev](https://currents.dev) for running parallel cypress tests using AWS CodeBuild CI - -The example [buildspec.yml](https://github.com/currents-dev/aws-codebuild-example/blob/main/buildspec.yml) defines a configuration for running cypress tests in parallel mode using 3 workers in [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html#batch_build_matrix). The example is designed to be executed within a [batch build](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html). - -- Note: The example uses [CODEBUILD_INITIATOR](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html) as a [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id). When testing interactively, the CODEBUILD_INITIATOR will be set to the username of the build initiator. When running a batched build, the variable will have the batch build id. - -- Note: get your record key from [Currents.dev](https://app.currents.dev) and set [AWS CodeBuild Environment Variable](https://docs.aws.amazon.com/codebuild/latest/userguide/change-project-console.html#change-project-console-environment) variable `CURRENTS_RECORD_KEY` - -- Note: set the `projectId` in `currents.config.js` - obtain the project id from [Currents.dev](https://app.currents.dev) - -- Note: use CLI arguments to customize your cypress-cloud runs, e.g.: `npx cypress-cloud run --parallel --record --key --group groupA` diff --git a/cypress/azure-devops/README.md b/cypress/azure-devops/README.md index 700290d..d711d1d 100644 --- a/cypress/azure-devops/README.md +++ b/cypress/azure-devops/README.md @@ -1,66 +1,3 @@ -# Cypress on Azure DevOps +# Cypress Azure Devops Example -- **Framework:** `cypress` -- **Use case:** `ci/azure-devops` -- **Source repository:** https://github.com/currents-dev/azure-devops-example - -## What this example does - -An example of running **Cypress** tests on **Azure DevOps Pipelines** using **Currents** as the orchestration/reporting service. The README explicitly positions it as “Running cypress tests using Currents dashboard in Azure DevOps”. - -## How this example is used - -- Azure DevOps pipeline runs **3 parallel jobs** via `strategy: parallel: 3`. -- It pulls secrets from an Azure DevOps **Variable Group** named `Currents` and maps the secret into `CURRENTS_RECORD_KEY`. -- It installs Node, caches npm + Cypress binary, runs `npm ci`, then runs: - - `npx currents run --record --parallel --key $CURRENTS_RECORD_KEY --ci-build-id $BUILD_BUILDNUMBER` -- Cypress + Currents CLI are included as dependencies (`cypress` and `@currents/cli`). -- Currents’ official docs for Cypress+Azure DevOps describe the same goal (parallel execution + Currents dashboard) and link to this repo as the reference config. - -## What scenarios are included - -- **Pipeline config**: `azure-pipelines.yml` showing: - - parallel strategy (3) - - caching steps - - Currents CLI run command + CI build id usage -- **Cypress config**: `cypress.config.js` showing: - - `baseUrl: "https://en.wikipedia.org/"` - - `specPattern: "cypress/integration/*.spec.js"` - - `projectId: "Ij0RfK"` - - video settings -- **Minimal README** that points to a “full guide”. - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Stop hardcoding the Currents project id** - - `projectId: "Ij0RfK"` is hardcoded in `cypress.config.js`. Switch to `process.env.CURRENTS_PROJECT_ID` and document it. -2. **Update the pipeline command to match current docs (or explain the difference)** - - The docs’ Azure DevOps snippet uses `npx cypress-cloud run ...` - - This repo uses `npx currents run ...` - - Either is fine if supported, but the repo should explicitly state *why* it uses `currents run` and whether `cypress-cloud` is now the preferred approach. -3. **Add a real Quickstart section** - - README is 1 line and assumes users click out. Add: prerequisites, required variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`), how to create the Variable Group, and what “success” looks like in Currents. -4. **Add `.env.example` + local run instructions** - - Let users validate locally before CI: `CURRENTS_RECORD_KEY=... CURRENTS_PROJECT_ID=... npx currents run ...`. -5. **Pretty-print the files** - - `azure-pipelines.yml`, `cypress.config.js`, and `package.json` are committed as single-line blobs, which makes them hard to read/copy. -6. **Add `package.json` scripts** - - Current `scripts.test` is the default “no test specified”. Add scripts like `test:currents` / `test:cypress` so users can run by name. - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **52** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +Running cypress tests using Currents dashboard in Azure DevOps - example repository. Check out the full guide at https://currents.dev/readme/ci-setup/azure-devops diff --git a/cypress/azure-devops/README.upstream.md b/cypress/azure-devops/README.upstream.md deleted file mode 100644 index d711d1d..0000000 --- a/cypress/azure-devops/README.upstream.md +++ /dev/null @@ -1,3 +0,0 @@ -# Cypress Azure Devops Example - -Running cypress tests using Currents dashboard in Azure DevOps - example repository. Check out the full guide at https://currents.dev/readme/ci-setup/azure-devops diff --git a/cypress/azure-devops/source__README.md b/cypress/azure-devops/source__README.md deleted file mode 100644 index d711d1d..0000000 --- a/cypress/azure-devops/source__README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Cypress Azure Devops Example - -Running cypress tests using Currents dashboard in Azure DevOps - example repository. Check out the full guide at https://currents.dev/readme/ci-setup/azure-devops diff --git a/cypress/circleci/README.md b/cypress/circleci/README.md index 568b959..435797c 100644 --- a/cypress/circleci/README.md +++ b/cypress/circleci/README.md @@ -1,65 +1,180 @@ -# Cypress on CircleCI - -- **Framework:** `cypress` -- **Use case:** `ci/circleci` -- **Source repository:** https://github.com/currents-dev/circleci-example - -## What this example does - -An example repo showing how to run **Cypress tests on CircleCI** and record/parallelize them to **Currents.dev** using `cypress-cloud`, including guidance for **alternative Cypress binaries** (Currents-hosted binaries / prebuilt images). - -## How this example is used - -1. Create a Currents account, get **ProjectId** + **Record Key**. -2. In CircleCI, set `CURRENTS_RECORD_KEY` via a **Context** (recommended) or env var. -3. Create `currents.config.js` with your `projectId` (repo has a sample but it’s hardcoded). -4. Run CircleCI using one of the provided configurations (all run **3 parallel containers**) that call: - - `npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY` -5. Choose how Cypress is installed: - - **Use Currents prebuilt image** `currentsdev/cypress-included:12.17.4` - - **Explicit download** via `CYPRESS_DOWNLOAD_MIRROR=https://cy-cdn.currents.dev npx cypress install --force` - - **Cypress Orb** (`cypress-io/cypress@3`) with either the default executor or a custom executor that uses the Currents image. - -## What scenarios are included - -- **Bare CircleCI config (no orbs)**: - - Using the Currents Docker image with preinstalled Cypress (`currentsdev/cypress-included:12.17.4`) - - Using a base image and explicitly downloading the alternative Cypress binary (download mirror) -- **Cypress Orb examples**: - - Orb install step with `post-install` to fetch the alternative Cypress binary, workspace persistence, then a parallel run job - - Custom executor (`currents-executor`) pointing at `currentsdev/cypress-included:12.17.4` -- **Dependency baseline**: - - `cypress@12.17.4`, `cypress-cloud`, and `typescript` in `package.json` -- **Currents config example**: - - `currents.config.js` with `projectId` + `batchSize: 3` - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Remove hardcoded `projectId`** - - `currents.config.js` currently hardcodes `projectId: "Ij0RfK"`; switch to `process.env.CURRENTS_PROJECT_ID` and document it (and/or CircleCI Context vars). -2. **Provide a `.env.example` + “Required variables” table** - - Explicitly list: `CURRENTS_RECORD_KEY` (secret), `CURRENTS_PROJECT_ID` (non-secret but should still be configurable), and optional `CURRENTS_CI_BUILD_ID` pattern (if you want consistent grouping). -3. **Format the repo files** - - `.circleci/config.yml`, `package.json`, and `currents.config.js` are effectively one-liners; pretty-print them so users can copy/edit safely. -4. **Add a quickstart that maps to the 3 scenarios** - - “Pick one: (A) prebuilt image, (B) explicit download, (C) Cypress Orb” with copy/paste snippets + where to set secrets in CircleCI. -5. **Make “alternative binaries” intent obvious** - - README mentions Currents-hosted Cypress app/binaries and supported versions; add a short explanation of *why* you’d choose mirror vs image (speed, reliability, avoiding blocked downloads). - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **24** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +# Currents.dev - CircleCI Example + +This is an example repository that showcases using [CircleCI](https://circleci.com) with [Currents.dev](https://currents.dev). + +We are hosting independent versions of the Cypress App and [docker images](https://hub.docker.com/r/currentsdev/cypress-included) with pre-installed binaries. Please refer to the [documentation](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) for the list of supported binaries and versions. + +The example [config file](https://github.com/currents-dev/circleci-example/blob/master/.circleci/config.yml) installs the custom Cypress App and runs 3 containers with Cypress tests in parallel using various setup scenarios. + +## Prerequisites + +- Create an account at https:/app.currents.dev. +- Obtain **ProjectId** and **Record Key**. +- Set `CURRENTS_RECORD_KEY`: + - create [CircleCI context](https://circleci.com/docs/contexts/) and set `CURRENTS_RECORD_KEY`. + - alternatively, set [Environment variable](https://circleci.com/docs/2.0/env-vars/) `CURRENTS_RECORD_KEY` +- Follow the setup instructions at https://currents.dev/readme/integration-with-cypress/cypress-cloud to create `currents.config.js` set your `projectId` + +## Bare CircleCI configuration + +Please refer to the setup scenario that fits your needs. + +### Use Docker image with pre-installed Cypress + +CircleCI configuration that uses Docker image with pre-installed cypress app. +Refer to the [documentation](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) for the list of supported binaries and versions. + +```yml +version: 2.1 + +jobs: + # Use pre-built image with alternative Cypress binary + noorbs currents-image: + parallelism: 3 + docker: + - image: currentsdev/cypress-included:12.17.4 + steps: + - checkout + - run: + name: Install Dependencies + command: npm ci + - run: + name: Run tests + command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY + +workflows: + noorbs: + jobs: + - noorbs currents-image: + context: currents +``` + +### Explicitly downloading alternative Cypress binary + +CircleCI configuration that explicitly downloads alternative Cypress binary. +Refer to the [documentation](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) for the list of supported binaries and versions. + +```yml +version: 2.1 + +jobs: + # Explicitly download Cypress binary + noorbs explicit-download: + parallelism: 3 + docker: + - image: cypress/base:18.16.1 + steps: + - checkout + - run: + name: Install dependencies + command: npm ci + - run: + name: Download Alternative Cypress Binaries + command: CYPRESS_DOWNLOAD_MIRROR=https://cy-cdn.currents.dev npx cypress install --force + - run: + name: Run tests + command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY + +workflows: + noorbs: + jobs: + - noorbs explicit-download: + context: currents +``` + +## Using Cypress Orb with default executor + +[Cypress Orb](https://circleci.com/developer/orbs/orb/cypress-io/cypress) has pre-defined commands that facilitate creating CircleCI configuration. The examples below show how to integrate Cypress tests with Currents using Cypress Orb and various setup scenarios. + +The examples below use [Custom Test Command](https://github.com/currents-dev/circleci-example/blob/master/.circleci/config.yml#L9) to run `cypress-cloud` for recording test results and parallelization with [Currents.dev](https://currents.dev) + +### Using `cypress/default` executor example + +The configuration below uses the default `cypress/default` [CircleCI executor](https://circleci.com/docs/executor-intro/) and installs custom Cypress binary during `cypress/install` step: + +```yml +version: 2.1 + +orbs: + cypress: cypress-io/cypress@3 + +jobs: + # Use cypress/default executor example + default-executor cypress-install: + executor: cypress/default + steps: + - cypress/install: + post-install: CYPRESS_DOWNLOAD_MIRROR=https://cy-cdn.currents.dev npx cypress install --force + - persist_to_workspace: + root: ~/ + paths: + - .cache/Cypress + - project + + default-executor cypress-run: + executor: cypress/default + parallelism: 3 + steps: + - attach_workspace: + at: ~/ + - cypress/run-tests: + cypress-command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY + +workflows: + with-orbs default-executor: + jobs: + - default-executor cypress-install + - default-executor cypress-run: + context: currents + requires: + - default-executor cypress-install +``` + +### Using custom executor with pre-installed Cypress App + +The configuration below uses the [custom executor](https://circleci.com/docs/executor-intro/) with pre-installed Cypress App. + +```yml +version: 2.1 + +orbs: + cypress: cypress-io/cypress@3 + +executors: + # define custom executors + currents-executor: + docker: + - image: currentsdev/cypress-included:12.17.4 + +jobs: + # Use currentsdev executor with pre-installed Cypress binary + custom-executor cypress-install: + executor: currents-executor + steps: + - cypress/install + - persist_to_workspace: + root: ~/ + paths: + - project + + custom-executor cypress-run: + executor: currents-executor + parallelism: 3 + steps: + - attach_workspace: + at: ~/ + - cypress/run-tests: + cypress-command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY + +workflows: + with-orbs custom-executor: + jobs: + - custom-executor cypress-run: + context: currents +``` + +--- + +Here's an example of the demo run in Currents.dev dashboard, note that 3 cypress agents were used as part of this run: + +https://user-images.githubusercontent.com/1637928/227703488-9bec973c-de2d-41d0-b811-dfffd370dfb7.mp4 diff --git a/cypress/circleci/README.upstream.md b/cypress/circleci/README.upstream.md deleted file mode 100644 index 435797c..0000000 --- a/cypress/circleci/README.upstream.md +++ /dev/null @@ -1,180 +0,0 @@ -# Currents.dev - CircleCI Example - -This is an example repository that showcases using [CircleCI](https://circleci.com) with [Currents.dev](https://currents.dev). - -We are hosting independent versions of the Cypress App and [docker images](https://hub.docker.com/r/currentsdev/cypress-included) with pre-installed binaries. Please refer to the [documentation](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) for the list of supported binaries and versions. - -The example [config file](https://github.com/currents-dev/circleci-example/blob/master/.circleci/config.yml) installs the custom Cypress App and runs 3 containers with Cypress tests in parallel using various setup scenarios. - -## Prerequisites - -- Create an account at https:/app.currents.dev. -- Obtain **ProjectId** and **Record Key**. -- Set `CURRENTS_RECORD_KEY`: - - create [CircleCI context](https://circleci.com/docs/contexts/) and set `CURRENTS_RECORD_KEY`. - - alternatively, set [Environment variable](https://circleci.com/docs/2.0/env-vars/) `CURRENTS_RECORD_KEY` -- Follow the setup instructions at https://currents.dev/readme/integration-with-cypress/cypress-cloud to create `currents.config.js` set your `projectId` - -## Bare CircleCI configuration - -Please refer to the setup scenario that fits your needs. - -### Use Docker image with pre-installed Cypress - -CircleCI configuration that uses Docker image with pre-installed cypress app. -Refer to the [documentation](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) for the list of supported binaries and versions. - -```yml -version: 2.1 - -jobs: - # Use pre-built image with alternative Cypress binary - noorbs currents-image: - parallelism: 3 - docker: - - image: currentsdev/cypress-included:12.17.4 - steps: - - checkout - - run: - name: Install Dependencies - command: npm ci - - run: - name: Run tests - command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY - -workflows: - noorbs: - jobs: - - noorbs currents-image: - context: currents -``` - -### Explicitly downloading alternative Cypress binary - -CircleCI configuration that explicitly downloads alternative Cypress binary. -Refer to the [documentation](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) for the list of supported binaries and versions. - -```yml -version: 2.1 - -jobs: - # Explicitly download Cypress binary - noorbs explicit-download: - parallelism: 3 - docker: - - image: cypress/base:18.16.1 - steps: - - checkout - - run: - name: Install dependencies - command: npm ci - - run: - name: Download Alternative Cypress Binaries - command: CYPRESS_DOWNLOAD_MIRROR=https://cy-cdn.currents.dev npx cypress install --force - - run: - name: Run tests - command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY - -workflows: - noorbs: - jobs: - - noorbs explicit-download: - context: currents -``` - -## Using Cypress Orb with default executor - -[Cypress Orb](https://circleci.com/developer/orbs/orb/cypress-io/cypress) has pre-defined commands that facilitate creating CircleCI configuration. The examples below show how to integrate Cypress tests with Currents using Cypress Orb and various setup scenarios. - -The examples below use [Custom Test Command](https://github.com/currents-dev/circleci-example/blob/master/.circleci/config.yml#L9) to run `cypress-cloud` for recording test results and parallelization with [Currents.dev](https://currents.dev) - -### Using `cypress/default` executor example - -The configuration below uses the default `cypress/default` [CircleCI executor](https://circleci.com/docs/executor-intro/) and installs custom Cypress binary during `cypress/install` step: - -```yml -version: 2.1 - -orbs: - cypress: cypress-io/cypress@3 - -jobs: - # Use cypress/default executor example - default-executor cypress-install: - executor: cypress/default - steps: - - cypress/install: - post-install: CYPRESS_DOWNLOAD_MIRROR=https://cy-cdn.currents.dev npx cypress install --force - - persist_to_workspace: - root: ~/ - paths: - - .cache/Cypress - - project - - default-executor cypress-run: - executor: cypress/default - parallelism: 3 - steps: - - attach_workspace: - at: ~/ - - cypress/run-tests: - cypress-command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY - -workflows: - with-orbs default-executor: - jobs: - - default-executor cypress-install - - default-executor cypress-run: - context: currents - requires: - - default-executor cypress-install -``` - -### Using custom executor with pre-installed Cypress App - -The configuration below uses the [custom executor](https://circleci.com/docs/executor-intro/) with pre-installed Cypress App. - -```yml -version: 2.1 - -orbs: - cypress: cypress-io/cypress@3 - -executors: - # define custom executors - currents-executor: - docker: - - image: currentsdev/cypress-included:12.17.4 - -jobs: - # Use currentsdev executor with pre-installed Cypress binary - custom-executor cypress-install: - executor: currents-executor - steps: - - cypress/install - - persist_to_workspace: - root: ~/ - paths: - - project - - custom-executor cypress-run: - executor: currents-executor - parallelism: 3 - steps: - - attach_workspace: - at: ~/ - - cypress/run-tests: - cypress-command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY - -workflows: - with-orbs custom-executor: - jobs: - - custom-executor cypress-run: - context: currents -``` - ---- - -Here's an example of the demo run in Currents.dev dashboard, note that 3 cypress agents were used as part of this run: - -https://user-images.githubusercontent.com/1637928/227703488-9bec973c-de2d-41d0-b811-dfffd370dfb7.mp4 diff --git a/cypress/circleci/source__README.md b/cypress/circleci/source__README.md deleted file mode 100644 index 435797c..0000000 --- a/cypress/circleci/source__README.md +++ /dev/null @@ -1,180 +0,0 @@ -# Currents.dev - CircleCI Example - -This is an example repository that showcases using [CircleCI](https://circleci.com) with [Currents.dev](https://currents.dev). - -We are hosting independent versions of the Cypress App and [docker images](https://hub.docker.com/r/currentsdev/cypress-included) with pre-installed binaries. Please refer to the [documentation](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) for the list of supported binaries and versions. - -The example [config file](https://github.com/currents-dev/circleci-example/blob/master/.circleci/config.yml) installs the custom Cypress App and runs 3 containers with Cypress tests in parallel using various setup scenarios. - -## Prerequisites - -- Create an account at https:/app.currents.dev. -- Obtain **ProjectId** and **Record Key**. -- Set `CURRENTS_RECORD_KEY`: - - create [CircleCI context](https://circleci.com/docs/contexts/) and set `CURRENTS_RECORD_KEY`. - - alternatively, set [Environment variable](https://circleci.com/docs/2.0/env-vars/) `CURRENTS_RECORD_KEY` -- Follow the setup instructions at https://currents.dev/readme/integration-with-cypress/cypress-cloud to create `currents.config.js` set your `projectId` - -## Bare CircleCI configuration - -Please refer to the setup scenario that fits your needs. - -### Use Docker image with pre-installed Cypress - -CircleCI configuration that uses Docker image with pre-installed cypress app. -Refer to the [documentation](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) for the list of supported binaries and versions. - -```yml -version: 2.1 - -jobs: - # Use pre-built image with alternative Cypress binary - noorbs currents-image: - parallelism: 3 - docker: - - image: currentsdev/cypress-included:12.17.4 - steps: - - checkout - - run: - name: Install Dependencies - command: npm ci - - run: - name: Run tests - command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY - -workflows: - noorbs: - jobs: - - noorbs currents-image: - context: currents -``` - -### Explicitly downloading alternative Cypress binary - -CircleCI configuration that explicitly downloads alternative Cypress binary. -Refer to the [documentation](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) for the list of supported binaries and versions. - -```yml -version: 2.1 - -jobs: - # Explicitly download Cypress binary - noorbs explicit-download: - parallelism: 3 - docker: - - image: cypress/base:18.16.1 - steps: - - checkout - - run: - name: Install dependencies - command: npm ci - - run: - name: Download Alternative Cypress Binaries - command: CYPRESS_DOWNLOAD_MIRROR=https://cy-cdn.currents.dev npx cypress install --force - - run: - name: Run tests - command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY - -workflows: - noorbs: - jobs: - - noorbs explicit-download: - context: currents -``` - -## Using Cypress Orb with default executor - -[Cypress Orb](https://circleci.com/developer/orbs/orb/cypress-io/cypress) has pre-defined commands that facilitate creating CircleCI configuration. The examples below show how to integrate Cypress tests with Currents using Cypress Orb and various setup scenarios. - -The examples below use [Custom Test Command](https://github.com/currents-dev/circleci-example/blob/master/.circleci/config.yml#L9) to run `cypress-cloud` for recording test results and parallelization with [Currents.dev](https://currents.dev) - -### Using `cypress/default` executor example - -The configuration below uses the default `cypress/default` [CircleCI executor](https://circleci.com/docs/executor-intro/) and installs custom Cypress binary during `cypress/install` step: - -```yml -version: 2.1 - -orbs: - cypress: cypress-io/cypress@3 - -jobs: - # Use cypress/default executor example - default-executor cypress-install: - executor: cypress/default - steps: - - cypress/install: - post-install: CYPRESS_DOWNLOAD_MIRROR=https://cy-cdn.currents.dev npx cypress install --force - - persist_to_workspace: - root: ~/ - paths: - - .cache/Cypress - - project - - default-executor cypress-run: - executor: cypress/default - parallelism: 3 - steps: - - attach_workspace: - at: ~/ - - cypress/run-tests: - cypress-command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY - -workflows: - with-orbs default-executor: - jobs: - - default-executor cypress-install - - default-executor cypress-run: - context: currents - requires: - - default-executor cypress-install -``` - -### Using custom executor with pre-installed Cypress App - -The configuration below uses the [custom executor](https://circleci.com/docs/executor-intro/) with pre-installed Cypress App. - -```yml -version: 2.1 - -orbs: - cypress: cypress-io/cypress@3 - -executors: - # define custom executors - currents-executor: - docker: - - image: currentsdev/cypress-included:12.17.4 - -jobs: - # Use currentsdev executor with pre-installed Cypress binary - custom-executor cypress-install: - executor: currents-executor - steps: - - cypress/install - - persist_to_workspace: - root: ~/ - paths: - - project - - custom-executor cypress-run: - executor: currents-executor - parallelism: 3 - steps: - - attach_workspace: - at: ~/ - - cypress/run-tests: - cypress-command: npx cypress-cloud run --parallel --record --key $CURRENTS_RECORD_KEY - -workflows: - with-orbs custom-executor: - jobs: - - custom-executor cypress-run: - context: currents -``` - ---- - -Here's an example of the demo run in Currents.dev dashboard, note that 3 cypress agents were used as part of this run: - -https://user-images.githubusercontent.com/1637928/227703488-9bec973c-de2d-41d0-b811-dfffd370dfb7.mp4 diff --git a/cypress/cucumber/README.md b/cypress/cucumber/README.md index f1e963e..aaaeac8 100644 --- a/cypress/cucumber/README.md +++ b/cypress/cucumber/README.md @@ -1,70 +1,14 @@ -# Cypress with Cucumber +# Cypress + cypress-cucumber-preprocessor + Currents -- **Framework:** `cypress` -- **Use case:** `features/cucumber` -- **Source repository:** https://github.com/currents-dev/currents-cypress-cucumber-example +Example of using `cypress-cucumber-preprocessor` with Currents. -## What this example does +- Use [`@currents/cli`](https://www.npmjs.com/package/@currents/cli) package to use Currents.dev as an alternative dashboard for ochestrating and reporting of cypress tests. +- Using `@currents/cli` allows using `npx currents` instead of `npx cypress`. Unfortunately `cypress-cucumber-preprocessor` has the `cypress` command hardcoded in its code, that's why an additional step is required to "patch" `cypress-cucumber-preprocessor` and use `currents` instead of `cypress`: + - the patch is in `patches` directory (it just replaces `cypress` command with `currents`) + - to apply the patch manually run `npx patch-package`. Read more about [`patch-package`](https://www.npmjs.com/package/patch-package). + - to apply the patch automatically as part of `npm install` add `"postinstall": "patch-package"` to `package.json:scripts` -Example of running **Cypress + `cypress-cucumber-preprocessor` (feature files / tags)** while reporting/orchestrating via **Currents** using `@currents/cli` (so you can run `npx currents` instead of `npx cypress`). +When patched, you can use `cypress-tags` command as usual, for example: +![currents-2024-03-15-11 53 54@2x](https://github.com/currents-dev/currents-cypress-cucumber-example/assets/1637928/e6ca384d-df05-43b8-9838-8faccc2dd950) -## How this example is used - -- Install dependencies (Cypress + cucumber preprocessor + `@currents/cli`). -- Configure Cypress: - - `specPattern: "**/*.{feature,features}"` so Cypress discovers Gherkin feature specs. - - uses `cypress-cucumber-preprocessor` as the `file:preprocessor` plugin. -- Patch requirement: - - `cypress-cucumber-preprocessor` hardcodes the `cypress` binary for its `cypress-tags` command, so the repo includes a `patch-package` patch that replaces the binary with `currents` (so tags work when running through Currents). -- Credentials: - - You need Currents **record key** and **project id** (README points to Currents app). - -## What scenarios are included - -- **Patch-package patch** that replaces the preprocessor’s internal executable from `cypress` → `currents`: - - `patches/cypress-cucumber-preprocessor+4.3.1.patch` -- **Cypress config** showing: - - feature-spec pattern - - projectId configured (currently hardcoded) - - cucumber preprocessor plugin wiring -- **Minimal cucumber plugin** (`cypress/plugins/index.js`) that hooks `file:preprocessor`. -- **README** describing why patching is needed and how to apply it. - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Make the README readable + structured** - - The raw README is basically 3 long lines; reformat into sections with fenced code blocks and a “Quickstart” flow. -2. **Add working scripts** - - `package.json` currently has `"test": "echo \"Error: no test specified\" && exit 1"`. Add scripts like: - - `postinstall: patch-package` (README recommends it but it’s not present) - - `test:currents` (e.g., `currents run ...` / whatever the intended command is) - - `tags` (e.g., `cypress-tags ...`) -3. **Stop hardcoding `projectId`** - - `cypress.config.js` hardcodes `projectId: "Ij0RfK"`; switch to `process.env.CURRENTS_PROJECT_ID` (and fail fast if missing). -4. **Explain “how to run” explicitly** - - README says “you can use `cypress-tags` as usual” but doesn’t show the exact command lines users should run (local + CI). Add copy/paste commands for: - - running feature specs - - running tagged subsets (using `cypress-tags`) - - recording to Currents (record key / project id) -5. **Modernize the cucumber stack note** - - This example uses `cypress-cucumber-preprocessor` + Cypress 10.11; add a short note about supported Cypress versions and alternatives if users are on newer Cypress where community preprocessors differ. (Right now it’s implied by deps only.) -6. **Pretty-print the code/config** - - `package.json`, `cypress.config.js`, and the patch file are one-line blobs; format them so people can learn/copy easier. - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **14** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +Note: get the record key and the project id at https://app.currents.dev diff --git a/cypress/cucumber/README.upstream.md b/cypress/cucumber/README.upstream.md deleted file mode 100644 index aaaeac8..0000000 --- a/cypress/cucumber/README.upstream.md +++ /dev/null @@ -1,14 +0,0 @@ -# Cypress + cypress-cucumber-preprocessor + Currents - -Example of using `cypress-cucumber-preprocessor` with Currents. - -- Use [`@currents/cli`](https://www.npmjs.com/package/@currents/cli) package to use Currents.dev as an alternative dashboard for ochestrating and reporting of cypress tests. -- Using `@currents/cli` allows using `npx currents` instead of `npx cypress`. Unfortunately `cypress-cucumber-preprocessor` has the `cypress` command hardcoded in its code, that's why an additional step is required to "patch" `cypress-cucumber-preprocessor` and use `currents` instead of `cypress`: - - the patch is in `patches` directory (it just replaces `cypress` command with `currents`) - - to apply the patch manually run `npx patch-package`. Read more about [`patch-package`](https://www.npmjs.com/package/patch-package). - - to apply the patch automatically as part of `npm install` add `"postinstall": "patch-package"` to `package.json:scripts` - -When patched, you can use `cypress-tags` command as usual, for example: -![currents-2024-03-15-11 53 54@2x](https://github.com/currents-dev/currents-cypress-cucumber-example/assets/1637928/e6ca384d-df05-43b8-9838-8faccc2dd950) - -Note: get the record key and the project id at https://app.currents.dev diff --git a/cypress/cucumber/source__README.md b/cypress/cucumber/source__README.md deleted file mode 100644 index aaaeac8..0000000 --- a/cypress/cucumber/source__README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Cypress + cypress-cucumber-preprocessor + Currents - -Example of using `cypress-cucumber-preprocessor` with Currents. - -- Use [`@currents/cli`](https://www.npmjs.com/package/@currents/cli) package to use Currents.dev as an alternative dashboard for ochestrating and reporting of cypress tests. -- Using `@currents/cli` allows using `npx currents` instead of `npx cypress`. Unfortunately `cypress-cucumber-preprocessor` has the `cypress` command hardcoded in its code, that's why an additional step is required to "patch" `cypress-cucumber-preprocessor` and use `currents` instead of `cypress`: - - the patch is in `patches` directory (it just replaces `cypress` command with `currents`) - - to apply the patch manually run `npx patch-package`. Read more about [`patch-package`](https://www.npmjs.com/package/patch-package). - - to apply the patch automatically as part of `npm install` add `"postinstall": "patch-package"` to `package.json:scripts` - -When patched, you can use `cypress-tags` command as usual, for example: -![currents-2024-03-15-11 53 54@2x](https://github.com/currents-dev/currents-cypress-cucumber-example/assets/1637928/e6ca384d-df05-43b8-9838-8faccc2dd950) - -Note: get the record key and the project id at https://app.currents.dev diff --git a/cypress/github-actions/README.md b/cypress/github-actions/README.md index 926aa66..223ffb5 100644 --- a/cypress/github-actions/README.md +++ b/cypress/github-actions/README.md @@ -1,113 +1,44 @@ -# GitHub Actions Examples +# Currents.dev - GitHub Actions Example -This directory contains examples of running Cypress tests with Currents on GitHub Actions. It combines two different scenarios: +This is an example repository that showcases using [Currents.dev](https://currents.dev) for running cypress tests on GitHub Actions. -1. **Basic GitHub Actions Setup**: Demonstrates how to run Cypress tests in parallel on GitHub Actions using `cypress-cloud`. -2. **Matrix Job URL Capture**: Demonstrates how to capture the GitHub Actions Job URL and expose it to Cypress tests for debugging purposes. +The example [workflow config file](https://github.com/currents-dev/gh-actions-example/blob/main/.github/workflows/currents.yml): -## Prerequisites +- runs 3 containers with cypress tests in parallel -Before running these examples, ensure you have: +- install [block-free Cypress binaries](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) -- A [Currents](https://currents.dev) account. -- A Project ID from Currents. -- A Record Key from Currents. +- uses [Custom Test Command](https://github.com/cypress-io/github-action#custom-test-command) to run `cypress-cloud` for recording test results and parallelization with [Currents.dev](https://currents.dev) -## 1. Basic GitHub Actions Setup +- Note: get your record key from [Currents.dev](https://app.currents.dev) and set [GH secret](https://docs.github.com/en/actions/reference/encrypted-secrets) variable `CURRENTS_RECORD_KEY` -This example shows a standard setup for running Cypress tests in parallel using GitHub Actions matrix strategy and `cypress-cloud` for orchestration and recording. +- Note: set the `projectId` in `currents.config.js` - obtain the project id from [Currents.dev](https://app.currents.dev) -### Key Features +- Note: use CLI arguments to customize your cypress-cloud runs, e.g.: `npx cypress-cloud run --parallel --record --key --group groupA` -- **Parallelization**: Runs 3 parallel containers using GitHub Actions matrix strategy. -- **Orchestration**: Uses `cypress-cloud` to distribute tests across containers. -- **Browser**: Runs tests in Chrome. -- **Cancellation**: Includes a step to cancel the run on Currents if the workflow is cancelled. -- **Custom Build ID**: Generates a unique build ID based on the repository, run ID, and run attempt. +Here's an example of how the demo workflow appears in Currents dashboard: -### Configuration Files +https://user-images.githubusercontent.com/1637928/227701237-db4d7a7f-b26b-46ac-ba6a-3806ede37671.mp4 -- **Workflow**: `.github/workflows/currents.yml` -- **Cypress Config**: `cypress.config.ts` -- **Test Files**: `cypress/e2e/*.spec.js` +## Using Alternative Cypress Binaries -### How it Works +Following [aggressive blocking](https://github.com/cypress-io/cypress/issues/28269) by Cypress.io team we released alternative, block-free Cypress binaries that were compiled from the MIT-licensed Cypress source code. -1. The workflow triggers on `push`. -2. It defines a matrix strategy with `containers: [1, 2, 3]`. -3. It installs dependencies using `npx ci`. -4. It installs a "block-free" version of Cypress to avoid potential blocking issues. -5. It runs `cypress-cloud` with the `--parallel` flag. -6. `cypress-cloud` communicates with Currents to receive the list of specs to run for each container. +The documentation is available at: https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries. -### Running Locally +The example in this repository uses [cypress-io/github-action@v6](https://github.com/cypress-io/github-action). `cypress-io/github-action` **caches and restores cypress binaries before running the tests** - you need to disable this behaviour to use the freshly installed non-blocking binaries: -To run this example locally (without parallelization): +```yml +- name: Run Cypress on Currents.dev + env: + # enable verbose logging + DEBUG: \@cypress/github-action + uses: cypress-io/github-action@v6 + continue-on-error: true -```bash -npx cypress-cloud run --record --key --config-file cypress.config.ts + with: + # 🔥 Set to false to prevent restoring cached blocking Cypress binary + install: false + command: | + npx cypress-cloud --record --parallel --browser chrome --key ${{ secrets.CURRENTS_RECORD_KEY }} --ci-build-id "${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt}}" ``` - -## 2. Matrix Job URL Capture - -This example demonstrates how to capture the specific URL of the GitHub Actions job running the tests and expose it as an environment variable (`MATRIX_JOB_URL`). This is useful for linking back to the CI logs from the Currents dashboard or for debugging failures. - -### Key Features - -- **Job URL Capture**: Uses `Tiryoh/gha-jobid-action` to fetch the current job's HTML URL. -- **Environment Variable**: Sets `MATRIX_JOB_URL` for use in tests. -- **Custom Config**: Uses a separate configuration file `cypress.matrix.config.js` to log the captured URL. - -### Configuration Files - -- **Workflow**: `.github/workflows/matrix-job-url.yml` -- **Cypress Config**: `cypress.matrix.config.js` -- **Test Files**: `cypress/integration/*.spec.js` - -### How it Works - -1. The workflow triggers on `push`. -2. It defines a matrix strategy with `containers: [1, 2, 3]`. -3. It uses the `Tiryoh/gha-jobid-action` to get the job ID and constructs the URL. -4. It exports the URL as `MATRIX_JOB_URL`. -5. It runs `npx currents run` pointing to `cypress.matrix.config.js`. -6. The `cypress.matrix.config.js` file has a `before:spec` hook that logs the `MATRIX_JOB_URL` to the console. - -### Running Locally - -To run this example locally (without the job URL, as it's CI-specific): - -```bash -npx currents run --record --key --config-file cypress.matrix.config.js -``` - -## Setup & Usage - -1. **Install Dependencies**: - ```bash - npm install - ``` - -2. **Configure Secrets**: - Add the following secrets to your GitHub repository: - - `CURRENTS_RECORD_KEY`: Your Currents Record Key. - - `CURRENTS_API_KEY`: Your Currents API Key (required for the cancellation step in the basic example). - -3. **Update Project ID**: - Update the `projectId` in `currents.config.js` (for the basic example) and `cypress.matrix.config.js` (for the matrix example) to match your Currents project ID. - - **currents.config.js**: - ```javascript - module.exports = { - projectId: "YOUR_PROJECT_ID", // Update this - }; - ``` - - **cypress.matrix.config.js**: - ```javascript - module.exports = defineConfig({ - // ... - projectId: "YOUR_PROJECT_ID", // Update this - // ... - }); - ``` diff --git a/cypress/github-actions/README.upstream.md b/cypress/github-actions/README.upstream.md deleted file mode 100644 index 223ffb5..0000000 --- a/cypress/github-actions/README.upstream.md +++ /dev/null @@ -1,44 +0,0 @@ -# Currents.dev - GitHub Actions Example - -This is an example repository that showcases using [Currents.dev](https://currents.dev) for running cypress tests on GitHub Actions. - -The example [workflow config file](https://github.com/currents-dev/gh-actions-example/blob/main/.github/workflows/currents.yml): - -- runs 3 containers with cypress tests in parallel - -- install [block-free Cypress binaries](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) - -- uses [Custom Test Command](https://github.com/cypress-io/github-action#custom-test-command) to run `cypress-cloud` for recording test results and parallelization with [Currents.dev](https://currents.dev) - -- Note: get your record key from [Currents.dev](https://app.currents.dev) and set [GH secret](https://docs.github.com/en/actions/reference/encrypted-secrets) variable `CURRENTS_RECORD_KEY` - -- Note: set the `projectId` in `currents.config.js` - obtain the project id from [Currents.dev](https://app.currents.dev) - -- Note: use CLI arguments to customize your cypress-cloud runs, e.g.: `npx cypress-cloud run --parallel --record --key --group groupA` - -Here's an example of how the demo workflow appears in Currents dashboard: - -https://user-images.githubusercontent.com/1637928/227701237-db4d7a7f-b26b-46ac-ba6a-3806ede37671.mp4 - -## Using Alternative Cypress Binaries - -Following [aggressive blocking](https://github.com/cypress-io/cypress/issues/28269) by Cypress.io team we released alternative, block-free Cypress binaries that were compiled from the MIT-licensed Cypress source code. - -The documentation is available at: https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries. - -The example in this repository uses [cypress-io/github-action@v6](https://github.com/cypress-io/github-action). `cypress-io/github-action` **caches and restores cypress binaries before running the tests** - you need to disable this behaviour to use the freshly installed non-blocking binaries: - -```yml -- name: Run Cypress on Currents.dev - env: - # enable verbose logging - DEBUG: \@cypress/github-action - uses: cypress-io/github-action@v6 - continue-on-error: true - - with: - # 🔥 Set to false to prevent restoring cached blocking Cypress binary - install: false - command: | - npx cypress-cloud --record --parallel --browser chrome --key ${{ secrets.CURRENTS_RECORD_KEY }} --ci-build-id "${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt}}" -``` diff --git a/cypress/github-actions/source__README.md b/cypress/github-actions/source__README.md deleted file mode 100644 index 223ffb5..0000000 --- a/cypress/github-actions/source__README.md +++ /dev/null @@ -1,44 +0,0 @@ -# Currents.dev - GitHub Actions Example - -This is an example repository that showcases using [Currents.dev](https://currents.dev) for running cypress tests on GitHub Actions. - -The example [workflow config file](https://github.com/currents-dev/gh-actions-example/blob/main/.github/workflows/currents.yml): - -- runs 3 containers with cypress tests in parallel - -- install [block-free Cypress binaries](https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries) - -- uses [Custom Test Command](https://github.com/cypress-io/github-action#custom-test-command) to run `cypress-cloud` for recording test results and parallelization with [Currents.dev](https://currents.dev) - -- Note: get your record key from [Currents.dev](https://app.currents.dev) and set [GH secret](https://docs.github.com/en/actions/reference/encrypted-secrets) variable `CURRENTS_RECORD_KEY` - -- Note: set the `projectId` in `currents.config.js` - obtain the project id from [Currents.dev](https://app.currents.dev) - -- Note: use CLI arguments to customize your cypress-cloud runs, e.g.: `npx cypress-cloud run --parallel --record --key --group groupA` - -Here's an example of how the demo workflow appears in Currents dashboard: - -https://user-images.githubusercontent.com/1637928/227701237-db4d7a7f-b26b-46ac-ba6a-3806ede37671.mp4 - -## Using Alternative Cypress Binaries - -Following [aggressive blocking](https://github.com/cypress-io/cypress/issues/28269) by Cypress.io team we released alternative, block-free Cypress binaries that were compiled from the MIT-licensed Cypress source code. - -The documentation is available at: https://currents.dev/readme/integration-with-cypress/alternative-cypress-binaries. - -The example in this repository uses [cypress-io/github-action@v6](https://github.com/cypress-io/github-action). `cypress-io/github-action` **caches and restores cypress binaries before running the tests** - you need to disable this behaviour to use the freshly installed non-blocking binaries: - -```yml -- name: Run Cypress on Currents.dev - env: - # enable verbose logging - DEBUG: \@cypress/github-action - uses: cypress-io/github-action@v6 - continue-on-error: true - - with: - # 🔥 Set to false to prevent restoring cached blocking Cypress binary - install: false - command: | - npx cypress-cloud --record --parallel --browser chrome --key ${{ secrets.CURRENTS_RECORD_KEY }} --ci-build-id "${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt}}" -``` diff --git a/cypress/netlify/README.md b/cypress/netlify/README.md index 932e525..13ff0af 100644 --- a/cypress/netlify/README.md +++ b/cypress/netlify/README.md @@ -1,61 +1,182 @@ [![astro](https://user-images.githubusercontent.com/3611928/167888733-9bf21eda-d051-46f3-9184-12b14e21a10a.png)](https://ntl.fyi/3LZGn73) - -# Cypress on Netlify -- **Framework:** `cypress` -- **Use case:** `ci/netlify` -- **Source repository:** https://github.com/currents-dev/currents-netlify-example +# Astro Quickstart Template -## What this example does +This is a bare-bones Astro project that has everything you need to quickly deploy it to [Netlify](https://netlify.com). -An example Netlify-deployed Astro site template that includes a **Netlify Build Plugin** configuration for **`netlify-plugin-currents`** via `netlify.toml`. +Hate reading, here's a video: https://youtu.be/SknFflQVOys! -> Note: The README describes this as an “Astro Quickstart Template” (Netlify template) and does **not** explain Currents; the Currents-specific part is in `netlify.toml`. +Love reading, here's blog post: www.netlify.app/blog/deploy-your-astro-project-fast/! -## How this example is used +## Table of Contents: -- Deploy the Astro template to Netlify (README gives standard “Deploy to Netlify” / CLI deploy instructions). -- Netlify build will use: - - `[build] command = "astro build"` and `publish = "dist"` - - A plugin block that references `package = "netlify-plugin-currents"` and enables it in `postBuild`. +- [Quick Setup + Deploy Option](#quick-setup--deploy-option) +- [Regular Setup](#regular-setup) + - [Cloning + Install Packages](#1-cloning--install-packages) + - [Deploying](#2-deploying) +- [Astro + Netlify Resources](#astro--netlify-resources) +- [Project Structure](#project-structure) +- [Styling](#styling) + - [Notes on Styling](#notes-on-styling) + - [Remove Styling](#remove-styling) +- [Commands](#commands) +- [Testing](#testing) + - [Included Default Testing](#included-default-testing) + - [Removing Renovate](#removing-renovate) + - [Removing Cypress](#removing-cypress) +- [Want to learn more?](#want-to-learn-more) -## What scenarios are included +## Quick Setup + Deploy Option -- **Astro quickstart project structure** (`src/`, `public/`, `astro.config.mjs`). -- **Cypress E2E** included as a dependency + config: - - `cypress` dependency in `package.json` - - `cypress.config.ts` configured with baseUrl `http://localhost:3000/` - - `cypress/e2e/` folder present -- **Netlify deploy config**: - - `netlify.toml` sets build/publish and includes the `netlify-plugin-currents` plugin entry. +Click this button and it will help you create a new repo, create a new Netlify project, and deploy! -## How to implement this in your own project +[![Deploy to Netlify Button](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify-templates/astro-quickstart) -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. +## Regular Setup -### Implementation notes from the audit + ### 1. Cloning + Install Packages -1. **Explain the Currents part in the README** - - Add a “Currents on Netlify” section: what `netlify-plugin-currents` does, what it expects (env vars, artifacts, etc.), and a minimal `netlify.toml` snippet. Right now the README doesn’t mention Currents at all. -2. **Fix / clarify plugin config correctness** - - `netlify.toml` has both `[plugins.inputs.postBuild]` and `[plugin.inputs]` (singular `plugin`) on the same line, which looks like a typo/misconfig. Reformat and verify the correct Netlify TOML schema. -3. **Add an `.env.example` (or Netlify UI env var list)** - - If the plugin requires tokens/keys, document them explicitly and point users to Netlify environment variables setup. -4. **Pretty-print committed files** - - `package.json`, `cypress.config.ts`, and `netlify.toml` are single-line blobs; format them for readability/copying. -5. **Make the example “Currents-first”** - - If this repo is meant to demonstrate Currents on Netlify, consider renaming/rewriting the README so it’s not primarily a generic Astro template, and include a minimal “verify it worked” checklist (what to look for in Netlify logs / Currents UI). + - Clone this repo with one of these options: -## Source markdown copied into this folder + - Click the 'Use this template' button at the top of the page + - Or via the command line `git clone https://github.com/netlify-templates/astro-quickstart` -- [`source__README.md`](source__README.md) + - Then install the necessary packages and run the project locally to make sure everything works. -## Repository content copied into this folder + ```bash + npm install + npm run dev + ``` -- Total tracked files copied: **17** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) + > Alternatively, you can run this locally with [the Netlify CLI](https://docs.netlify.com/cli/get-started/)'s by running the `netlify dev` command for more options like receiving a live preview to share (`netlify dev --live`) and the ability to test [Netlify Functions](https://www.netlify.com/products/functions) and [redirects](https://docs.netlify.com/routing/redirects/). + + ### 2. Deploying + - Install the Netlify CLI globally `npm install netlify-cli -g` + + - Run `npm run build` + + - Then use the `netlify deploy` for a deploy preview link or `netlify deploy --prod` to deploy to production + + Here are a few other ways you can deploy this template: + + - Use the Netlify CLI's create from template command `netlify sites:create-template astro-quickstart` which will create a repo, Netlify project, and deploy it + + - If you want to utilize continuous deployment through GitHub webhooks, run the Netlify command `netlify init` to create a new project based on your repo or `netlify link` to connect your repo to an existing project + +## Astro + Netlify Resources + +Here are some resources to help you on your Astro + Netlify coding fun! + +- [Astro on Netlify Integration Page](https://docs.netlify.com/integrations/frameworks/astro) + +- [Build wicked fast sites with Astro: An Introduction](https://www.netlify.com/blog/2021/07/08/build-wicked-fast-sites-with-astro-an-introduction/#main) + +- [A Template for Building Shopify Stores with Astro and the Storefront API](https://www.netlify.com/blog/2021/07/23/build-a-modern-shopping-site-with-astro-and-serverless-functions) + +Hope this template helps :) Happy coding 👩🏻‍💻! + +--- + +## Project Structure + +Inside of your Astro project, you'll see the following folders and files: + +``` +/ +├── public/ +│ └── favicon.ico +├── src/ +│ ├── components/ +│ │ └── Layout.astro +│ ├── pages/ +│ │ └── index.astro +│ └── style/ +│ └── demo-styling.css +└── package.json +``` + +Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name. + +There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components or layouts. + +Any static assets, like images, can be placed in the `public/` directory. + +## Styling + +We've added some modern styling to this template using css within an external stylesheet, this will allow you to easily remove our styling and add in your own. + +If you decide that you want to keep our styling you can review our style notes below. + +### Notes on Styling + +The variables below give you the ability to change the gradient colors of the blobs and are interpolated into the URL string of the background-img within the body. + +```css +// Controls the blob blur gradient colors within the main tag's svg +--top-right-blur-1: #20C6B7; +--top-right-blur-2: #4D9ABF; +--bttm-left-blur-1: #FF5C02; +--bttm-left-blur-2: #FFCDB1; +``` + +### Remove Styling + +If you decide that our styling is not for you, all you'll need to do is remove the [demo-styling.css](https://github.com/netlify-templates/astro-quickstart/tree/main/src/style/demo-styling.css) file. + + +## Commands + +All commands are run from the root of the project, from a terminal: + +| Command | Action | +| :---------------- | :------------------------------------------- | +| `npm install` | Installs dependencies | +| `npm run dev` | Starts local dev server at `localhost:3000` | +| `npm run build` | Build your production site to `./dist/` | +| `npm run preview` | Preview your build locally, before deploying | + +## Testing + +### Included Default Testing + +We’ve included some tooling that helps us maintain these templates. This template currently uses: + +- [Renovate](https://www.mend.io/free-developer-tools/renovate/) - to regularly update our dependencies +- [Cypress](https://www.cypress.io/) - to run tests against how the template runs in the browser +- [Cypress Netlify Build Plugin](https://github.com/cypress-io/netlify-plugin-cypress) - to run our tests during our build process + +If your team is not interested in this tooling, you can remove them with ease! + +### Removing Renovate + +In order to keep our project up-to-date with dependencies we use a tool called [Renovate](https://github.com/marketplace/renovate). If you’re not interested in this tooling, delete the `renovate.json` file and commit that onto your main branch. + +### Removing Cypress + +For our testing, we use [Cypress](https://www.cypress.io/) for end-to-end testing. This makes sure that we can validate that our templates are rendering and displaying as we’d expect. By default, we have Cypress not generate deploy links if our tests don’t pass. If you’d like to keep Cypress and still generate the deploy links, go into your `netlify.toml` and delete the plugin configuration lines: + +```diff +[[plugins]] + package = "netlify-plugin-cypress" +- [plugins.inputs.postBuild] +- enable = true +- +- [plugins.inputs] +- enable = false  +``` + +If you’d like to remove the `netlify-plugin-cypress` build plugin entirely, you’d need to delete the entire block above instead. And then make sure sure to remove the package from the dependencies using: + +```bash +npm uninstall -D netlify-plugin-cypress +``` + +And lastly if you’d like to remove Cypress entirely, delete the entire `cypress` folder and the `cypress.config.ts` file. Then remove the dependency using: + +```bash +npm uninstall cypress +``` + +## Want to learn more? + +Feel free to check [our documentation](https://github.com/withastro/astro) or jump into our [Discord server](https://astro.build/chat). diff --git a/cypress/netlify/README.upstream.md b/cypress/netlify/README.upstream.md deleted file mode 100644 index 13ff0af..0000000 --- a/cypress/netlify/README.upstream.md +++ /dev/null @@ -1,182 +0,0 @@ - [![astro](https://user-images.githubusercontent.com/3611928/167888733-9bf21eda-d051-46f3-9184-12b14e21a10a.png)](https://ntl.fyi/3LZGn73) - -# Astro Quickstart Template - -This is a bare-bones Astro project that has everything you need to quickly deploy it to [Netlify](https://netlify.com). - -Hate reading, here's a video: https://youtu.be/SknFflQVOys! - -Love reading, here's blog post: www.netlify.app/blog/deploy-your-astro-project-fast/! - -## Table of Contents: - -- [Quick Setup + Deploy Option](#quick-setup--deploy-option) -- [Regular Setup](#regular-setup) - - [Cloning + Install Packages](#1-cloning--install-packages) - - [Deploying](#2-deploying) -- [Astro + Netlify Resources](#astro--netlify-resources) -- [Project Structure](#project-structure) -- [Styling](#styling) - - [Notes on Styling](#notes-on-styling) - - [Remove Styling](#remove-styling) -- [Commands](#commands) -- [Testing](#testing) - - [Included Default Testing](#included-default-testing) - - [Removing Renovate](#removing-renovate) - - [Removing Cypress](#removing-cypress) -- [Want to learn more?](#want-to-learn-more) - -## Quick Setup + Deploy Option - -Click this button and it will help you create a new repo, create a new Netlify project, and deploy! - -[![Deploy to Netlify Button](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify-templates/astro-quickstart) - -## Regular Setup - - ### 1. Cloning + Install Packages - - - Clone this repo with one of these options: - - - Click the 'Use this template' button at the top of the page - - Or via the command line `git clone https://github.com/netlify-templates/astro-quickstart` - - - Then install the necessary packages and run the project locally to make sure everything works. - - ```bash - npm install - npm run dev - ``` - - > Alternatively, you can run this locally with [the Netlify CLI](https://docs.netlify.com/cli/get-started/)'s by running the `netlify dev` command for more options like receiving a live preview to share (`netlify dev --live`) and the ability to test [Netlify Functions](https://www.netlify.com/products/functions) and [redirects](https://docs.netlify.com/routing/redirects/). - - ### 2. Deploying - - Install the Netlify CLI globally `npm install netlify-cli -g` - - - Run `npm run build` - - - Then use the `netlify deploy` for a deploy preview link or `netlify deploy --prod` to deploy to production - - Here are a few other ways you can deploy this template: - - - Use the Netlify CLI's create from template command `netlify sites:create-template astro-quickstart` which will create a repo, Netlify project, and deploy it - - - If you want to utilize continuous deployment through GitHub webhooks, run the Netlify command `netlify init` to create a new project based on your repo or `netlify link` to connect your repo to an existing project - -## Astro + Netlify Resources - -Here are some resources to help you on your Astro + Netlify coding fun! - -- [Astro on Netlify Integration Page](https://docs.netlify.com/integrations/frameworks/astro) - -- [Build wicked fast sites with Astro: An Introduction](https://www.netlify.com/blog/2021/07/08/build-wicked-fast-sites-with-astro-an-introduction/#main) - -- [A Template for Building Shopify Stores with Astro and the Storefront API](https://www.netlify.com/blog/2021/07/23/build-a-modern-shopping-site-with-astro-and-serverless-functions) - -Hope this template helps :) Happy coding 👩🏻‍💻! - ---- - -## Project Structure - -Inside of your Astro project, you'll see the following folders and files: - -``` -/ -├── public/ -│ └── favicon.ico -├── src/ -│ ├── components/ -│ │ └── Layout.astro -│ ├── pages/ -│ │ └── index.astro -│ └── style/ -│ └── demo-styling.css -└── package.json -``` - -Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name. - -There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components or layouts. - -Any static assets, like images, can be placed in the `public/` directory. - -## Styling - -We've added some modern styling to this template using css within an external stylesheet, this will allow you to easily remove our styling and add in your own. - -If you decide that you want to keep our styling you can review our style notes below. - -### Notes on Styling - -The variables below give you the ability to change the gradient colors of the blobs and are interpolated into the URL string of the background-img within the body. - -```css -// Controls the blob blur gradient colors within the main tag's svg ---top-right-blur-1: #20C6B7; ---top-right-blur-2: #4D9ABF; ---bttm-left-blur-1: #FF5C02; ---bttm-left-blur-2: #FFCDB1; -``` - -### Remove Styling - -If you decide that our styling is not for you, all you'll need to do is remove the [demo-styling.css](https://github.com/netlify-templates/astro-quickstart/tree/main/src/style/demo-styling.css) file. - - -## Commands - -All commands are run from the root of the project, from a terminal: - -| Command | Action | -| :---------------- | :------------------------------------------- | -| `npm install` | Installs dependencies | -| `npm run dev` | Starts local dev server at `localhost:3000` | -| `npm run build` | Build your production site to `./dist/` | -| `npm run preview` | Preview your build locally, before deploying | - -## Testing - -### Included Default Testing - -We’ve included some tooling that helps us maintain these templates. This template currently uses: - -- [Renovate](https://www.mend.io/free-developer-tools/renovate/) - to regularly update our dependencies -- [Cypress](https://www.cypress.io/) - to run tests against how the template runs in the browser -- [Cypress Netlify Build Plugin](https://github.com/cypress-io/netlify-plugin-cypress) - to run our tests during our build process - -If your team is not interested in this tooling, you can remove them with ease! - -### Removing Renovate - -In order to keep our project up-to-date with dependencies we use a tool called [Renovate](https://github.com/marketplace/renovate). If you’re not interested in this tooling, delete the `renovate.json` file and commit that onto your main branch. - -### Removing Cypress - -For our testing, we use [Cypress](https://www.cypress.io/) for end-to-end testing. This makes sure that we can validate that our templates are rendering and displaying as we’d expect. By default, we have Cypress not generate deploy links if our tests don’t pass. If you’d like to keep Cypress and still generate the deploy links, go into your `netlify.toml` and delete the plugin configuration lines: - -```diff -[[plugins]] - package = "netlify-plugin-cypress" -- [plugins.inputs.postBuild] -- enable = true -- -- [plugins.inputs] -- enable = false  -``` - -If you’d like to remove the `netlify-plugin-cypress` build plugin entirely, you’d need to delete the entire block above instead. And then make sure sure to remove the package from the dependencies using: - -```bash -npm uninstall -D netlify-plugin-cypress -``` - -And lastly if you’d like to remove Cypress entirely, delete the entire `cypress` folder and the `cypress.config.ts` file. Then remove the dependency using: - -```bash -npm uninstall cypress -``` - -## Want to learn more? - -Feel free to check [our documentation](https://github.com/withastro/astro) or jump into our [Discord server](https://astro.build/chat). diff --git a/cypress/netlify/source__README.md b/cypress/netlify/source__README.md deleted file mode 100644 index 13ff0af..0000000 --- a/cypress/netlify/source__README.md +++ /dev/null @@ -1,182 +0,0 @@ - [![astro](https://user-images.githubusercontent.com/3611928/167888733-9bf21eda-d051-46f3-9184-12b14e21a10a.png)](https://ntl.fyi/3LZGn73) - -# Astro Quickstart Template - -This is a bare-bones Astro project that has everything you need to quickly deploy it to [Netlify](https://netlify.com). - -Hate reading, here's a video: https://youtu.be/SknFflQVOys! - -Love reading, here's blog post: www.netlify.app/blog/deploy-your-astro-project-fast/! - -## Table of Contents: - -- [Quick Setup + Deploy Option](#quick-setup--deploy-option) -- [Regular Setup](#regular-setup) - - [Cloning + Install Packages](#1-cloning--install-packages) - - [Deploying](#2-deploying) -- [Astro + Netlify Resources](#astro--netlify-resources) -- [Project Structure](#project-structure) -- [Styling](#styling) - - [Notes on Styling](#notes-on-styling) - - [Remove Styling](#remove-styling) -- [Commands](#commands) -- [Testing](#testing) - - [Included Default Testing](#included-default-testing) - - [Removing Renovate](#removing-renovate) - - [Removing Cypress](#removing-cypress) -- [Want to learn more?](#want-to-learn-more) - -## Quick Setup + Deploy Option - -Click this button and it will help you create a new repo, create a new Netlify project, and deploy! - -[![Deploy to Netlify Button](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify-templates/astro-quickstart) - -## Regular Setup - - ### 1. Cloning + Install Packages - - - Clone this repo with one of these options: - - - Click the 'Use this template' button at the top of the page - - Or via the command line `git clone https://github.com/netlify-templates/astro-quickstart` - - - Then install the necessary packages and run the project locally to make sure everything works. - - ```bash - npm install - npm run dev - ``` - - > Alternatively, you can run this locally with [the Netlify CLI](https://docs.netlify.com/cli/get-started/)'s by running the `netlify dev` command for more options like receiving a live preview to share (`netlify dev --live`) and the ability to test [Netlify Functions](https://www.netlify.com/products/functions) and [redirects](https://docs.netlify.com/routing/redirects/). - - ### 2. Deploying - - Install the Netlify CLI globally `npm install netlify-cli -g` - - - Run `npm run build` - - - Then use the `netlify deploy` for a deploy preview link or `netlify deploy --prod` to deploy to production - - Here are a few other ways you can deploy this template: - - - Use the Netlify CLI's create from template command `netlify sites:create-template astro-quickstart` which will create a repo, Netlify project, and deploy it - - - If you want to utilize continuous deployment through GitHub webhooks, run the Netlify command `netlify init` to create a new project based on your repo or `netlify link` to connect your repo to an existing project - -## Astro + Netlify Resources - -Here are some resources to help you on your Astro + Netlify coding fun! - -- [Astro on Netlify Integration Page](https://docs.netlify.com/integrations/frameworks/astro) - -- [Build wicked fast sites with Astro: An Introduction](https://www.netlify.com/blog/2021/07/08/build-wicked-fast-sites-with-astro-an-introduction/#main) - -- [A Template for Building Shopify Stores with Astro and the Storefront API](https://www.netlify.com/blog/2021/07/23/build-a-modern-shopping-site-with-astro-and-serverless-functions) - -Hope this template helps :) Happy coding 👩🏻‍💻! - ---- - -## Project Structure - -Inside of your Astro project, you'll see the following folders and files: - -``` -/ -├── public/ -│ └── favicon.ico -├── src/ -│ ├── components/ -│ │ └── Layout.astro -│ ├── pages/ -│ │ └── index.astro -│ └── style/ -│ └── demo-styling.css -└── package.json -``` - -Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name. - -There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components or layouts. - -Any static assets, like images, can be placed in the `public/` directory. - -## Styling - -We've added some modern styling to this template using css within an external stylesheet, this will allow you to easily remove our styling and add in your own. - -If you decide that you want to keep our styling you can review our style notes below. - -### Notes on Styling - -The variables below give you the ability to change the gradient colors of the blobs and are interpolated into the URL string of the background-img within the body. - -```css -// Controls the blob blur gradient colors within the main tag's svg ---top-right-blur-1: #20C6B7; ---top-right-blur-2: #4D9ABF; ---bttm-left-blur-1: #FF5C02; ---bttm-left-blur-2: #FFCDB1; -``` - -### Remove Styling - -If you decide that our styling is not for you, all you'll need to do is remove the [demo-styling.css](https://github.com/netlify-templates/astro-quickstart/tree/main/src/style/demo-styling.css) file. - - -## Commands - -All commands are run from the root of the project, from a terminal: - -| Command | Action | -| :---------------- | :------------------------------------------- | -| `npm install` | Installs dependencies | -| `npm run dev` | Starts local dev server at `localhost:3000` | -| `npm run build` | Build your production site to `./dist/` | -| `npm run preview` | Preview your build locally, before deploying | - -## Testing - -### Included Default Testing - -We’ve included some tooling that helps us maintain these templates. This template currently uses: - -- [Renovate](https://www.mend.io/free-developer-tools/renovate/) - to regularly update our dependencies -- [Cypress](https://www.cypress.io/) - to run tests against how the template runs in the browser -- [Cypress Netlify Build Plugin](https://github.com/cypress-io/netlify-plugin-cypress) - to run our tests during our build process - -If your team is not interested in this tooling, you can remove them with ease! - -### Removing Renovate - -In order to keep our project up-to-date with dependencies we use a tool called [Renovate](https://github.com/marketplace/renovate). If you’re not interested in this tooling, delete the `renovate.json` file and commit that onto your main branch. - -### Removing Cypress - -For our testing, we use [Cypress](https://www.cypress.io/) for end-to-end testing. This makes sure that we can validate that our templates are rendering and displaying as we’d expect. By default, we have Cypress not generate deploy links if our tests don’t pass. If you’d like to keep Cypress and still generate the deploy links, go into your `netlify.toml` and delete the plugin configuration lines: - -```diff -[[plugins]] - package = "netlify-plugin-cypress" -- [plugins.inputs.postBuild] -- enable = true -- -- [plugins.inputs] -- enable = false  -``` - -If you’d like to remove the `netlify-plugin-cypress` build plugin entirely, you’d need to delete the entire block above instead. And then make sure sure to remove the package from the dependencies using: - -```bash -npm uninstall -D netlify-plugin-cypress -``` - -And lastly if you’d like to remove Cypress entirely, delete the entire `cypress` folder and the `cypress.config.ts` file. Then remove the dependency using: - -```bash -npm uninstall cypress -``` - -## Want to learn more? - -Feel free to check [our documentation](https://github.com/withastro/astro) or jump into our [Discord server](https://astro.build/chat). diff --git a/cypress/nx/README.md b/cypress/nx/README.md index 67bcd21..3288a56 100644 --- a/cypress/nx/README.md +++ b/cypress/nx/README.md @@ -1,61 +1,67 @@ -# Cypress in Nx Monorepo +# currents-nx-example -- **Framework:** `cypress` -- **Use case:** `workspace/nx` -- **Source repository:** https://github.com/currents-dev/currents-nx-example +Example of using [`@currents/nx`](https://www.npmjs.com/package/@currents/nx) plugin for integrating cypress with alternative orchestration services - [Currents](https://currents.dev) and [Sorry Cypress](https://sorry-cypress.dev) -## What this example does +## Walkthrough -An example Nx workspace showing how to use the **`@currents/nx` executor** to run **Cypress** tests and record/parallelize them with **Currents** (or alternatively **Sorry Cypress**). +[`@currents/nx`](https://github.com/currents-dev/currents-nx/tree/main) is an NX plugin that runs cypress tests with the provided configuration options while using alternative orchestration services. -## How this example is used +You can recreate the example following the next steps. -- The README walks you through creating an Nx workspace + web app, installing `@currents/nx`, then adding a new target using the `@currents/nx:currents` executor. -- In this repo, that target already exists as `frontend-e2e:currents` in `apps/frontend-e2e/project.json` and enables `record` + `parallel`, points to a Cypress config, and sets `devServerTarget`. -- You then run: - - `nx run frontend-e2e:currents --record --key --ci-build-id hello-currents-nx` - - or (if options are set in config) omit flags and run with just `--ci-build-id`. -- Cypress itself is configured with `cypress-cloud/plugin` and includes a Currents `projectId`. +```sh -## What scenarios are included +# Create an "empty" workspace +npx create-nx-workspace@latest currents-nx-example +cd currents-nx-example -- **Nx target configuration for Currents executor** - - `apps/frontend-e2e/project.json` shows the `currents` target using `@currents/nx:currents` with `record: true`, `parallel: true`, and `devServerTarget: frontend:serve`. -- **Cypress configuration wired to cypress-cloud** - - `apps/frontend-e2e/cypress.config.js` uses `cypress-cloud/plugin`, defines `specPattern`, and sets `projectId`. -- **Repo-level dependencies** - - `package.json` includes `@currents/nx`, `cypress`, and `cypress-cloud`. -- **README “recreate the example” steps** - - End-to-end instructions for creating the Nx workspace and adding the executor target. +# Create a dummy web project, choose any CSS styling +# That will create a new project with `@nrwl/cypress` pre-installed and configured +npm i -D @nx/web +nx g @nx/web:app frontend -## How to implement this in your own project +# Install @currents/nx +npm i -D @currents/nx -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. +# Configure a new target in apps/frontend-e2e/project.json +vim apps/frontend-e2e/project.json +``` -### Implementation notes from the audit +Set executor value to `"@currents/nx:currents"` -1. **Remove hardcoded / placeholder values** - - `project.json` has `key` and `ciBuildId` set to **documentation URLs** (not usable values). Replace with env-var usage or omit these options and document the CLI flags. - - `cypress.config.js` hardcodes `projectId: 'Ij0RfK'`; make it env-driven and fail fast if missing. -2. **Fix typos / consistency** - - README snippet references `cypres.config.ts` (typo) while this repo uses `apps/frontend-e2e/cypress.config.js`. Clean up the README example so it matches reality. -3. **Pretty-print the repo files** - - Key files are committed as single-line blobs (`package.json`, `project.json`, `cypress.config.js`, README), which makes the example hard to learn from. -4. **Add a minimal CI workflow** - - A small GitHub Actions example running `nx run frontend-e2e:currents ...` would make the “CI use case” copy/pasteable (this repo currently doesn’t surface a workflow in the README). -5. **Make “Currents vs Sorry Cypress” explicit** - - README says it supports both, but doesn’t show the exact knob (`cloudServiceUrl` etc.). Add a short section + example config for Sorry Cypress mode and where to set it. +```json +{ + "executor": "@currents/nx:currents", + "options": { + "record": true, + "parallel": true, + "cypressConfig": "apps/app-e2e/cypres.config.ts", + "devServerTarget": "my-react-app:serve", + "testingType": "e2e" + } +} +``` -## Source markdown copied into this folder +- Get `projectId` and `recordKey` from https://app.currents.dev +- Update the projectId in `cypress.config.js` file +- Set the key either in configuration or as CLI flag -- [`source__README.md`](source__README.md) +Now you can start recording your tests to Currents or Sorry Cypress. -## Repository content copied into this folder +```sh +nx run frontend-e2e:currents --record --key --ci-build-id hello-currents-nx +``` -- Total tracked files copied: **49** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +While having those options defined, you can omit the corresponding CLI flags: + +```sh +nx run frontend-e2e:currents --ci-build-id hello-currents-nx-001 +``` + +### Misc + +- Learn more about [Parallelizing Cypress](https://currents.dev/readme/guides/parallelization) tests +- Explore how to use [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id) to organize your builds + +Here's a visual example of this demo project sending the results to Currents dashboard + +![Kapture 2021-11-19 at 01 14 50](https://user-images.githubusercontent.com/1637928/142597762-3cc0009f-d030-46aa-b273-1c31300c65f6.gif) diff --git a/cypress/nx/README.upstream.md b/cypress/nx/README.upstream.md deleted file mode 100644 index 3288a56..0000000 --- a/cypress/nx/README.upstream.md +++ /dev/null @@ -1,67 +0,0 @@ -# currents-nx-example - -Example of using [`@currents/nx`](https://www.npmjs.com/package/@currents/nx) plugin for integrating cypress with alternative orchestration services - [Currents](https://currents.dev) and [Sorry Cypress](https://sorry-cypress.dev) - -## Walkthrough - -[`@currents/nx`](https://github.com/currents-dev/currents-nx/tree/main) is an NX plugin that runs cypress tests with the provided configuration options while using alternative orchestration services. - -You can recreate the example following the next steps. - -```sh - -# Create an "empty" workspace -npx create-nx-workspace@latest currents-nx-example -cd currents-nx-example - -# Create a dummy web project, choose any CSS styling -# That will create a new project with `@nrwl/cypress` pre-installed and configured -npm i -D @nx/web -nx g @nx/web:app frontend - -# Install @currents/nx -npm i -D @currents/nx - -# Configure a new target in apps/frontend-e2e/project.json -vim apps/frontend-e2e/project.json -``` - -Set executor value to `"@currents/nx:currents"` - -```json -{ - "executor": "@currents/nx:currents", - "options": { - "record": true, - "parallel": true, - "cypressConfig": "apps/app-e2e/cypres.config.ts", - "devServerTarget": "my-react-app:serve", - "testingType": "e2e" - } -} -``` - -- Get `projectId` and `recordKey` from https://app.currents.dev -- Update the projectId in `cypress.config.js` file -- Set the key either in configuration or as CLI flag - -Now you can start recording your tests to Currents or Sorry Cypress. - -```sh -nx run frontend-e2e:currents --record --key --ci-build-id hello-currents-nx -``` - -While having those options defined, you can omit the corresponding CLI flags: - -```sh -nx run frontend-e2e:currents --ci-build-id hello-currents-nx-001 -``` - -### Misc - -- Learn more about [Parallelizing Cypress](https://currents.dev/readme/guides/parallelization) tests -- Explore how to use [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id) to organize your builds - -Here's a visual example of this demo project sending the results to Currents dashboard - -![Kapture 2021-11-19 at 01 14 50](https://user-images.githubusercontent.com/1637928/142597762-3cc0009f-d030-46aa-b273-1c31300c65f6.gif) diff --git a/cypress/nx/source__README.md b/cypress/nx/source__README.md deleted file mode 100644 index 3288a56..0000000 --- a/cypress/nx/source__README.md +++ /dev/null @@ -1,67 +0,0 @@ -# currents-nx-example - -Example of using [`@currents/nx`](https://www.npmjs.com/package/@currents/nx) plugin for integrating cypress with alternative orchestration services - [Currents](https://currents.dev) and [Sorry Cypress](https://sorry-cypress.dev) - -## Walkthrough - -[`@currents/nx`](https://github.com/currents-dev/currents-nx/tree/main) is an NX plugin that runs cypress tests with the provided configuration options while using alternative orchestration services. - -You can recreate the example following the next steps. - -```sh - -# Create an "empty" workspace -npx create-nx-workspace@latest currents-nx-example -cd currents-nx-example - -# Create a dummy web project, choose any CSS styling -# That will create a new project with `@nrwl/cypress` pre-installed and configured -npm i -D @nx/web -nx g @nx/web:app frontend - -# Install @currents/nx -npm i -D @currents/nx - -# Configure a new target in apps/frontend-e2e/project.json -vim apps/frontend-e2e/project.json -``` - -Set executor value to `"@currents/nx:currents"` - -```json -{ - "executor": "@currents/nx:currents", - "options": { - "record": true, - "parallel": true, - "cypressConfig": "apps/app-e2e/cypres.config.ts", - "devServerTarget": "my-react-app:serve", - "testingType": "e2e" - } -} -``` - -- Get `projectId` and `recordKey` from https://app.currents.dev -- Update the projectId in `cypress.config.js` file -- Set the key either in configuration or as CLI flag - -Now you can start recording your tests to Currents or Sorry Cypress. - -```sh -nx run frontend-e2e:currents --record --key --ci-build-id hello-currents-nx -``` - -While having those options defined, you can omit the corresponding CLI flags: - -```sh -nx run frontend-e2e:currents --ci-build-id hello-currents-nx-001 -``` - -### Misc - -- Learn more about [Parallelizing Cypress](https://currents.dev/readme/guides/parallelization) tests -- Explore how to use [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id) to organize your builds - -Here's a visual example of this demo project sending the results to Currents dashboard - -![Kapture 2021-11-19 at 01 14 50](https://user-images.githubusercontent.com/1637928/142597762-3cc0009f-d030-46aa-b273-1c31300c65f6.gif) diff --git a/generic-reporter/jest/github-actions/README.md b/generic-reporter/jest/github-actions/README.md index 0a76db8..5435005 100644 --- a/generic-reporter/jest/github-actions/README.md +++ b/generic-reporter/jest/github-actions/README.md @@ -1,61 +1,25 @@ -# Jest Reporting on GitHub Actions +# Currents + Jest on GitHub Actions Example -- **Framework:** `generic-reporter` -- **Use case:** `jest` -- **Source repository:** https://github.com/currents-dev/currents-jest-github-actions-example +## About -## What this example does +This repository demonstrates how to report test results generated by Jest to [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting and analysing CI tests. -A minimal example showing how to report **Jest** test results to **Currents** and run Jest **in parallel** on GitHub Actions using Jest’s native `--shard` support (matrix with 2 shards/containers). +This example runs Jest tests in [parallel](https://jestjs.io/docs/cli#--shard) using GitHub actions matrix with 2 containers. -## How this example is used +## How to reproduce -1. Create a Currents account and get **Project Id** + **Record Key**. -2. Store `CURRENTS_RECORD_KEY` as a GitHub Actions **Repository Secret**. -3. Add `@currents/cmd` + `@currents/jest`, and configure `@currents/jest` as a Jest reporter (via `jest.config.js`). -4. GitHub Actions runs two shards: - - `npx jest --shard=${{ matrix.shard }}/2` -5. Upload results to Currents: - - `npx currents upload --project-id mdXsz8 --ci-build-id --` (record key comes from `secrets.CURRENTS_RECORD_KEY`). +Follow the steps to reproduce this example: -## What scenarios are included +- Create an account at https://app.currents.dev and obtain Project Id and Record Key +- Save the Record Key as [Repository Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) `CURRENTS_RECORD_KEY` +- Add `@currents/cmd` and `@currents/jest` as a dependency +- Add `@currents/jest` as Jest reporter (see `./jest.config.js`) +- Configure GitHub actions [workflow](.github/workflows/test.yml): + - run the tests: `npm run test` + - upload the test results to Currents: `npx currents upload ...` -- **GitHub Actions workflow** showing parallel shards + upload: - - `.github/workflows/test.yml` -- **Jest reporter wiring** - - `jest.config.js` exists and is referenced by the README as the place where `@currents/jest` is configured. -- **Code + tests scaffold** - - `src/` and `tests/` folders exist in the repo. -- **README walkthrough** - - Repo README explains the reproduction steps and points to the workflow file. +## Resources -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Stop hardcoding `--project-id mdXsz8` in the workflow** - - Use `secrets.CURRENTS_PROJECT_ID` or GitHub “Variables”, and document it in the README. -2. **Reformat the README and workflow files** - - The README is effectively a single-line blob in raw form, and the workflow YAML is also one line, making it hard to copy/modify. -3. **Make the “what gets uploaded” explicit** - - Add 3–5 lines: where Jest output/report is generated, how `@currents/jest` emits results, and what `currents upload` expects (paths/outputs). (Right now it’s implied.) -4. **Add caching + `npm ci`** - - Switch `npm install` → `npm ci` and add `actions/cache` for npm to speed up runs (common CI best-practice). -5. **Add a “Local run” section** - - Show local env var usage (`CURRENTS_RECORD_KEY`, project id) and a one-command run (no Actions) so people can validate before pushing. - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **10** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +- 📖 [Currents documentation](https://docs.currents.dev) +- [`@currents/cmd`](https://docs.currents.dev/resources/reporters/currents-cmd) +- [`@currents/jest`](https://docs.currents.dev/resources/reporters/currents-jest) diff --git a/generic-reporter/jest/github-actions/README.upstream.md b/generic-reporter/jest/github-actions/README.upstream.md deleted file mode 100644 index 5435005..0000000 --- a/generic-reporter/jest/github-actions/README.upstream.md +++ /dev/null @@ -1,25 +0,0 @@ -# Currents + Jest on GitHub Actions Example - -## About - -This repository demonstrates how to report test results generated by Jest to [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting and analysing CI tests. - -This example runs Jest tests in [parallel](https://jestjs.io/docs/cli#--shard) using GitHub actions matrix with 2 containers. - -## How to reproduce - -Follow the steps to reproduce this example: - -- Create an account at https://app.currents.dev and obtain Project Id and Record Key -- Save the Record Key as [Repository Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) `CURRENTS_RECORD_KEY` -- Add `@currents/cmd` and `@currents/jest` as a dependency -- Add `@currents/jest` as Jest reporter (see `./jest.config.js`) -- Configure GitHub actions [workflow](.github/workflows/test.yml): - - run the tests: `npm run test` - - upload the test results to Currents: `npx currents upload ...` - -## Resources - -- 📖 [Currents documentation](https://docs.currents.dev) -- [`@currents/cmd`](https://docs.currents.dev/resources/reporters/currents-cmd) -- [`@currents/jest`](https://docs.currents.dev/resources/reporters/currents-jest) diff --git a/generic-reporter/jest/github-actions/source__README.md b/generic-reporter/jest/github-actions/source__README.md deleted file mode 100644 index 5435005..0000000 --- a/generic-reporter/jest/github-actions/source__README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Currents + Jest on GitHub Actions Example - -## About - -This repository demonstrates how to report test results generated by Jest to [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting and analysing CI tests. - -This example runs Jest tests in [parallel](https://jestjs.io/docs/cli#--shard) using GitHub actions matrix with 2 containers. - -## How to reproduce - -Follow the steps to reproduce this example: - -- Create an account at https://app.currents.dev and obtain Project Id and Record Key -- Save the Record Key as [Repository Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) `CURRENTS_RECORD_KEY` -- Add `@currents/cmd` and `@currents/jest` as a dependency -- Add `@currents/jest` as Jest reporter (see `./jest.config.js`) -- Configure GitHub actions [workflow](.github/workflows/test.yml): - - run the tests: `npm run test` - - upload the test results to Currents: `npx currents upload ...` - -## Resources - -- 📖 [Currents documentation](https://docs.currents.dev) -- [`@currents/cmd`](https://docs.currents.dev/resources/reporters/currents-cmd) -- [`@currents/jest`](https://docs.currents.dev/resources/reporters/currents-jest) diff --git a/generic-reporter/junit/junit-xml/README.md b/generic-reporter/junit/junit-xml/README.md index d21d053..19ac433 100644 --- a/generic-reporter/junit/junit-xml/README.md +++ b/generic-reporter/junit/junit-xml/README.md @@ -1,76 +1,19 @@ -junit-xml-reporter - -# Generic JUnit XML Reporting - -- **Framework:** `generic-reporter` -- **Use case:** `junit` -- **Source repository:** https://github.com/currents-dev/currents-junit-xml-example - -## What this example does - -A monorepo of **JUnit XML → Currents** examples showing how to take JUnit XML produced by various test frameworks, **convert** it with `@currents/cmd` (`currents convert`), and **upload** it to Currents (`currents upload`). - -## How this example is used - -General workflow (per package/framework): -1) Run the framework to generate a JUnit XML file (e.g., `results.xml` / `report.xml`). -2) Convert: `npx currents convert --input-format=junit --input-file= --framework= --framework-version=` -3) Upload: `npx currents upload --key= --project-id=` +# Currents.dev - JUnit XML report example -Repo-level: -- Uses npm workspaces (`packages/*`) and depends on `@currents/cmd` at the root. +This is an example repository that showcases integrating variout testing frameworks with [Currents.dev](https://currents.dev). -Framework-specific notes: -- **WebdriverIO**: generates **multiple** JUnit XML files (`results-*.xml`) and requires combining them into a single `combined-results.xml` via `scripts/combineResults.js` before converting/uploading. -- **NodeJS test runner**: uses `node --test` with `@currents/node-test-reporter` to write `report.xml`, then converts with `--framework=node`. -- **Vitest**: runs `vitest --outputFile.junit=./results.xml` and then converts using `--framework=vitest`. -- The repo contains `.github/workflows/` (intended to show “Vitest - parallel runs on GitHub Actions”), but GitHub directory listing wasn’t readable in the rendered page during this audit. - -## What scenarios are included - -Root README links to these examples (each under `packages/`): -- **Postman (Newman)**: run `newman ... -r cli,junit --reporter-junit-export ./results.xml`, then convert with `--framework=postman --framework-version=v11.2.0`. -- **Vitest** (+ note about parallel runs on GitHub Actions): produces `results.xml` and converts with `--framework=vitest --framework-version=v3.4.0`. -- **WebdriverIO**: JUnit reporter output files in `./results`, combine with `scripts/combineResults.js`, then convert with `--framework=wdio`. -- **NodeJS Test Runner**: `npm run test` generates `report.xml`, `npm run convert`, then upload. - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Format / readability** - - Multiple READMEs and scripts are committed as single-line text, which makes them hard to follow/copy. (Root + package READMEs, combine script.) -2. **Add a real “Quickstart (end-to-end)” at the root** - - Right now root README only says `npm install` + links. Add: required env vars, where to get them, and a single “pick one package and run these commands” flow. -3. **Standardize scripts per package** - - Vitest package only has `test` script; NodeJS has `test` + `convert`; Postman/Wdio have no scripts. Add `test`, `convert`, `upload` scripts in each package so it’s consistent. -4. **Make WebdriverIO combine step clearer + safer** - - README calls `node ../../scripts/combineResults.js` without args, while the script prints a usage message if args aren’t provided (even though it has defaults). Update README to show explicit `--reports-dir` / `--output-file` usage and explain expected input file naming (`results-*.xml`). -5. **Fix typos / polish** - - Root: “variout”; Postman: “Postname”. These reduce trust when people copy the repo as a template. -6. **Expose the GitHub Actions example clearly** - - Since the root README claims a GitHub Actions parallel Vitest example, link directly to the workflow file path and include a snippet in the vitest README. (Workflows folder exists but wasn’t inspectable in this view.) -7. **Add `.env.example`** - - Provide `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`, optional `CURRENTS_CI_BUILD_ID`, plus a note that `currents upload` can take args or env vars (show one consistent approach). +junit-xml-reporter -## Source markdown copied into this folder +## Setup -- [`source__packages__nodejs-test-runner__README.md`](source__packages__nodejs-test-runner__README.md) -- [`source__packages__postman__README.md`](source__packages__postman__README.md) -- [`source__packages__vitest-sharded__README.md`](source__packages__vitest-sharded__README.md) -- [`source__packages__vitest__README.md`](source__packages__vitest__README.md) -- [`source__packages__wdio__README.md`](source__packages__wdio__README.md) -- [`source__README.md`](source__README.md) -- [`source__scripts__README.md`](source__scripts__README.md) +```sh +npm install +``` -## Repository content copied into this folder +## Examples -- Total tracked files copied: **53** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +- [Postman](./packages/postman) +- [Vitest](./packages/vitest) +- [Vitest - parallel runs on GitHub Actions](./packages/vitest) +- [WebdriverIO](./packages/wdio) +- [NodeJS Test Runner](./packages/nodejs-test-runner) diff --git a/generic-reporter/junit/junit-xml/README.upstream.md b/generic-reporter/junit/junit-xml/README.upstream.md deleted file mode 100644 index 19ac433..0000000 --- a/generic-reporter/junit/junit-xml/README.upstream.md +++ /dev/null @@ -1,19 +0,0 @@ -# Currents.dev - JUnit XML report example - -This is an example repository that showcases integrating variout testing frameworks with [Currents.dev](https://currents.dev). - -junit-xml-reporter - -## Setup - -```sh -npm install -``` - -## Examples - -- [Postman](./packages/postman) -- [Vitest](./packages/vitest) -- [Vitest - parallel runs on GitHub Actions](./packages/vitest) -- [WebdriverIO](./packages/wdio) -- [NodeJS Test Runner](./packages/nodejs-test-runner) diff --git a/generic-reporter/junit/junit-xml/source__README.md b/generic-reporter/junit/junit-xml/source__README.md deleted file mode 100644 index 19ac433..0000000 --- a/generic-reporter/junit/junit-xml/source__README.md +++ /dev/null @@ -1,19 +0,0 @@ -# Currents.dev - JUnit XML report example - -This is an example repository that showcases integrating variout testing frameworks with [Currents.dev](https://currents.dev). - -junit-xml-reporter - -## Setup - -```sh -npm install -``` - -## Examples - -- [Postman](./packages/postman) -- [Vitest](./packages/vitest) -- [Vitest - parallel runs on GitHub Actions](./packages/vitest) -- [WebdriverIO](./packages/wdio) -- [NodeJS Test Runner](./packages/nodejs-test-runner) diff --git a/generic-reporter/junit/nodejs-github-actions/README.md b/generic-reporter/junit/nodejs-github-actions/README.md index 768522b..a40179f 100644 --- a/generic-reporter/junit/nodejs-github-actions/README.md +++ b/generic-reporter/junit/nodejs-github-actions/README.md @@ -1,61 +1,28 @@ -# Node.js JUnit Reporting on GitHub Actions +# Currents + Node.js on GitHub Actions Example -- **Framework:** `generic-reporter` -- **Use case:** `junit` -- **Source repository:** https://github.com/currents-dev/currents-nodejs-github-actions-example +## About -## What this example does +This repository demonstrates how to report test results generated by Node.js to [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting and analyzing CI tests. -A minimal example showing how to report **Node.js test results** (Node’s built-in `node --test`) to **Currents** from **GitHub Actions** using `@currents/node-test-reporter` + `@currents/cmd`. -## How this example is used +## How to reproduce -- The intended flow is: - 1. Run Node tests with Currents’ Node test reporter outputting a JUnit XML file (`report.xml`). - 2. Convert JUnit into Currents format with `npx currents convert --input-format=junit --input-file=./report.xml --framework=node`. - 3. Upload to Currents with `npx currents upload` using `CURRENTS_RECORD_KEY` from GitHub Secrets. -- CI runs in **2 shards** using `node --test --test-shard=${{ matrix.shard }}/2 ... tests/**.test.mjs`. -- There’s also a Currents docs page pointing to this repo as the Node + GitHub Actions example. +Follow the steps to reproduce this example: -## What scenarios are included +- Create an account at https://app.currents.dev and obtain Project Id and Record Key +- Save the Record Key as [Repository Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) `CURRENTS_RECORD_KEY` +- Add `@currents/cmd` and `@currents/node-test-reporter` as a dependency +- Configure GitHub actions [workflow](.github/workflows/test.yml): + - run the tests: `npm run test` + - convert the results using `npm run convert` + - upload the test results to Currents: `npx currents upload` -- **GitHub Actions workflow** demonstrating sharded runs + convert + upload: - - `.github/workflows/test.yml` -- **Example scripts** - - `npm run test` generates `report.xml` via Node’s test runner + Currents reporter. - - `npm run convert` converts `report.xml` into Currents format. -- **Assets** - - `image.png` (screenshot of a run in Currents UI) referenced in the README. -- **Test suite** - - A `tests/` folder is present (workflow targets `tests/**.test.mjs`). +## Resources -## How to implement this in your own project +- 📖 [Currents documentation](https://docs.currents.dev) +- [`@currents/cmd`](https://docs.currents.dev/resources/reporters/currents-cmd) +- [`@currents/node-test-reporter`](https://docs.currents.dev/resources/reporters/currents-node-test-reporter) -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. +## Currents application example for a run -### Implementation notes from the audit - -1. **Stop hardcoding IDs / staging URLs in the workflow** - - Workflow currently hardcodes `--project-id JOw2i3` and sets `CURRENTS_API_URL=https://cy-staging.currents.dev/`. Make these repo variables/secrets and default to production docs. -2. **Reformat the README + YAML + JSON** - - README and workflow are essentially single-line in raw form, which is hard to read/copy. Break into sections + fenced blocks. -3. **Clarify where “Project Id” is set** - - README tells users to obtain Project Id, but doesn’t clearly state it’s passed via `--project-id` in the workflow. Add an explicit note. -4. **Add a “Local run” section** - - Example: how to set `CURRENTS_RECORD_KEY` locally, run `npm run test`, run `npm run convert`, then upload (and whether to use production vs staging). -5. **Make the “report” script safe** - - `package.json` has a `report` script that uploads to staging without showing project id / build id args. Either remove it or make it a documented helper that requires env vars. - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **16** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +![example](image.png) \ No newline at end of file diff --git a/generic-reporter/junit/nodejs-github-actions/README.upstream.md b/generic-reporter/junit/nodejs-github-actions/README.upstream.md deleted file mode 100644 index a40179f..0000000 --- a/generic-reporter/junit/nodejs-github-actions/README.upstream.md +++ /dev/null @@ -1,28 +0,0 @@ -# Currents + Node.js on GitHub Actions Example - -## About - -This repository demonstrates how to report test results generated by Node.js to [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting and analyzing CI tests. - - -## How to reproduce - -Follow the steps to reproduce this example: - -- Create an account at https://app.currents.dev and obtain Project Id and Record Key -- Save the Record Key as [Repository Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) `CURRENTS_RECORD_KEY` -- Add `@currents/cmd` and `@currents/node-test-reporter` as a dependency -- Configure GitHub actions [workflow](.github/workflows/test.yml): - - run the tests: `npm run test` - - convert the results using `npm run convert` - - upload the test results to Currents: `npx currents upload` - -## Resources - -- 📖 [Currents documentation](https://docs.currents.dev) -- [`@currents/cmd`](https://docs.currents.dev/resources/reporters/currents-cmd) -- [`@currents/node-test-reporter`](https://docs.currents.dev/resources/reporters/currents-node-test-reporter) - -## Currents application example for a run - -![example](image.png) \ No newline at end of file diff --git a/generic-reporter/junit/nodejs-github-actions/source__README.md b/generic-reporter/junit/nodejs-github-actions/source__README.md deleted file mode 100644 index a40179f..0000000 --- a/generic-reporter/junit/nodejs-github-actions/source__README.md +++ /dev/null @@ -1,28 +0,0 @@ -# Currents + Node.js on GitHub Actions Example - -## About - -This repository demonstrates how to report test results generated by Node.js to [Currents](https://currents.dev) - a cloud platform for debugging, troubleshooting and analyzing CI tests. - - -## How to reproduce - -Follow the steps to reproduce this example: - -- Create an account at https://app.currents.dev and obtain Project Id and Record Key -- Save the Record Key as [Repository Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) `CURRENTS_RECORD_KEY` -- Add `@currents/cmd` and `@currents/node-test-reporter` as a dependency -- Configure GitHub actions [workflow](.github/workflows/test.yml): - - run the tests: `npm run test` - - convert the results using `npm run convert` - - upload the test results to Currents: `npx currents upload` - -## Resources - -- 📖 [Currents documentation](https://docs.currents.dev) -- [`@currents/cmd`](https://docs.currents.dev/resources/reporters/currents-cmd) -- [`@currents/node-test-reporter`](https://docs.currents.dev/resources/reporters/currents-node-test-reporter) - -## Currents application example for a run - -![example](image.png) \ No newline at end of file diff --git a/playwright/bdd-cucumber/README.md b/playwright/bdd-cucumber/README.md index c01521b..6dabcfa 100644 --- a/playwright/bdd-cucumber/README.md +++ b/playwright/bdd-cucumber/README.md @@ -1,70 +1,83 @@ -# Playwright with BDD / Cucumber +# Playwright + Currents + playwright-bdd (Cucumber) -- **Framework:** `playwright` -- **Use case:** `features/bdd-cucumber` -- **Source repository:** https://github.com/currents-dev/currents-playwright-bdd-cucumber-example +This repository showcases running [Playwright](https://playwright.dev) + [Currents](https://currents.dev) + [playwright-bdd](https://github.com/vitalets/playwright-bdd) to run BDD tests, while using [Currents](https://currents.dev) as the reporting dashboard. -## What this example does +

+ +

-A working example of **Playwright + BDD (Gherkin/Cucumber-style)** using **playwright-bdd**, with results reported to **Currents** via `@currents/playwright`. ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/README.md)) +## Why? -## How this example is used +`cucumber-js` is a mature and popular test runner, however, it is different from the native Playwright test runner - those are not compatible. To utilize the native Playwright test runner with BDD it is suggested to use [playwright-bdd](https://github.com/vitalets/playwright-bdd). -1. Create a Currents org/project and obtain **Record Key** + **Project Id**. ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/README.md)) -2. Install dependencies and browsers: - - `npm install` - - `npx playwright install` ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/README.md)) -3. Configure Currents reporting in `playwright.config.ts` (currently includes placeholders for `recordKey` and `projectId`). ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/playwright.config.ts)) -4. Run: - - `npm test` (runs `bddgen` then `playwright test`). ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/package.json)) +Read more at: https://www.cy2pw.com/cucumber. -## What scenarios are included +## Documentation -### BDD feature files -- `features/homepage.feature` (includes an intentionally failing assertion: expects “Oh no!” title on API reference). ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/features/homepage.feature)) -- `features/todopage.feature` (todo flow scenarios; includes a screenshot comparison step). ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/features/todopage.feature)) +The repo contains a few BDD tests with one test that always fails (intentionally): -### Currents + Playwright wiring -- `playwright.config.ts`: - - uses `@currents/playwright` reporter - - enables artifacts (trace/screenshot on failure) - - defines Chromium + Firefox projects - - uses `defineBddConfig` to generate tests from feature files. ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/playwright.config.ts)) +- [features/homepage.feature](features/homepage.feature) - has intentionally failing test +- [features/todopage.feature](features/todopage.feature) -### Useful scripts -- `test`, `test:todo` (tag-based), `test:chromium`, watch mode, and `steps` export. ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/package.json)) +To reproduce the setup: -### Tag → browser behavior -- `steps/fixtures.ts` skips tests tagged `@firefox` unless the current Playwright project is Firefox. ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/steps/fixtures.ts)) +- Create an organization, get your **Record Key** and **Project Id** at https://app.currents.dev -## How to implement this in your own project +- Clone repo +- Install dependencies -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. + ```sh + npm install + ``` -### Implementation notes from the audit +- Install browsers -1. **Move secrets to env vars** - - Replace placeholders in `playwright.config.ts` with `process.env.CURRENTS_RECORD_KEY` / `process.env.CURRENTS_PROJECT_ID`. - - Add `.env.example` and document it. ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/playwright.config.ts)) -2. **Make CI build ID deterministic in CI** - - `ciBuildId: Date.now().toString()` is fine locally, but in CI it’s better to use the CI run/build id when available (GitHub Actions / Jenkins / etc.). ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/playwright.config.ts)) -3. **Clarify the intentional failure** - - README says one test fails intentionally; add which scenario and why, so users don’t think setup is broken. ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/README.md)) -4. **Add a copy/paste Quickstart** - - Install → set env vars → run `npm test` → where to see results in Currents. -5. **Clarify `baseURL` expectations** - - Config sets `baseURL: http://localhost:3000`; add a note about what should be running there (or adjust baseURL to match the intended demo target). ([raw.githubusercontent.com](https://raw.githubusercontent.com/currents-dev/currents-playwright-bdd-cucumber-example/main/playwright.config.ts)) + ```sh + npx playwright install + ``` -## Source markdown copied into this folder +- Set **Record Key** and **Project Id** in `playwright.config.ts` -- [`source__README.md`](source__README.md) +- Run tests -## Repository content copied into this folder + ```sh + npm test + ``` -- Total tracked files copied: **16** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) + Output: + + ```plain + =============================================== + Uploading results to Currents.dev... + Cloud Run Finished: https://app.currents.dev/run/1f2e431c6d46675e + ================================================ + ``` + +Additional resources: + +- Playwright Features on Currents: https://currents.dev/playwright +- Integration Documentation: https://currents.dev/readme/integration-with-playwright/currents-playwright +- CI Build ID Guide: https://currents.dev/readme/guides/ci-build-id + +## Results + +The results are being reported to Currents for more efficient troubleshooting, and monitoring test suite flakiness and performance. + +Currents will collect the following information: + +- console output +- screenshots +- videos +- trace files +- timing +- outcomes +- flaky tests +- error details +- tags for more convenient management of the tests: + +![currents-2024-01-24-15 26 34@2x](https://github.com/currents-dev/currents-playwright-bdd-cucumber-example/assets/1637928/44e38f3c-56f4-469e-884e-71a528ee4dca) + +![currents-2024-01-24-15 29 19@2x](https://github.com/currents-dev/currents-playwright-bdd-cucumber-example/assets/1637928/4ac06f8b-ff38-4f88-8ca0-b3d147d9dd96) + + +- diff --git a/playwright/bdd-cucumber/README.upstream.md b/playwright/bdd-cucumber/README.upstream.md deleted file mode 100644 index 6dabcfa..0000000 --- a/playwright/bdd-cucumber/README.upstream.md +++ /dev/null @@ -1,83 +0,0 @@ -# Playwright + Currents + playwright-bdd (Cucumber) - -This repository showcases running [Playwright](https://playwright.dev) + [Currents](https://currents.dev) + [playwright-bdd](https://github.com/vitalets/playwright-bdd) to run BDD tests, while using [Currents](https://currents.dev) as the reporting dashboard. - -

- -

- -## Why? - -`cucumber-js` is a mature and popular test runner, however, it is different from the native Playwright test runner - those are not compatible. To utilize the native Playwright test runner with BDD it is suggested to use [playwright-bdd](https://github.com/vitalets/playwright-bdd). - -Read more at: https://www.cy2pw.com/cucumber. - -## Documentation - -The repo contains a few BDD tests with one test that always fails (intentionally): - -- [features/homepage.feature](features/homepage.feature) - has intentionally failing test -- [features/todopage.feature](features/todopage.feature) - -To reproduce the setup: - -- Create an organization, get your **Record Key** and **Project Id** at https://app.currents.dev - -- Clone repo -- Install dependencies - - ```sh - npm install - ``` - -- Install browsers - - ```sh - npx playwright install - ``` - -- Set **Record Key** and **Project Id** in `playwright.config.ts` - -- Run tests - - ```sh - npm test - ``` - - Output: - - ```plain - =============================================== - Uploading results to Currents.dev... - Cloud Run Finished: https://app.currents.dev/run/1f2e431c6d46675e - ================================================ - ``` - -Additional resources: - -- Playwright Features on Currents: https://currents.dev/playwright -- Integration Documentation: https://currents.dev/readme/integration-with-playwright/currents-playwright -- CI Build ID Guide: https://currents.dev/readme/guides/ci-build-id - -## Results - -The results are being reported to Currents for more efficient troubleshooting, and monitoring test suite flakiness and performance. - -Currents will collect the following information: - -- console output -- screenshots -- videos -- trace files -- timing -- outcomes -- flaky tests -- error details -- tags for more convenient management of the tests: - -![currents-2024-01-24-15 26 34@2x](https://github.com/currents-dev/currents-playwright-bdd-cucumber-example/assets/1637928/44e38f3c-56f4-469e-884e-71a528ee4dca) - -![currents-2024-01-24-15 29 19@2x](https://github.com/currents-dev/currents-playwright-bdd-cucumber-example/assets/1637928/4ac06f8b-ff38-4f88-8ca0-b3d147d9dd96) - - -- diff --git a/playwright/bdd-cucumber/source__README.md b/playwright/bdd-cucumber/source__README.md deleted file mode 100644 index 6dabcfa..0000000 --- a/playwright/bdd-cucumber/source__README.md +++ /dev/null @@ -1,83 +0,0 @@ -# Playwright + Currents + playwright-bdd (Cucumber) - -This repository showcases running [Playwright](https://playwright.dev) + [Currents](https://currents.dev) + [playwright-bdd](https://github.com/vitalets/playwright-bdd) to run BDD tests, while using [Currents](https://currents.dev) as the reporting dashboard. - -

- -

- -## Why? - -`cucumber-js` is a mature and popular test runner, however, it is different from the native Playwright test runner - those are not compatible. To utilize the native Playwright test runner with BDD it is suggested to use [playwright-bdd](https://github.com/vitalets/playwright-bdd). - -Read more at: https://www.cy2pw.com/cucumber. - -## Documentation - -The repo contains a few BDD tests with one test that always fails (intentionally): - -- [features/homepage.feature](features/homepage.feature) - has intentionally failing test -- [features/todopage.feature](features/todopage.feature) - -To reproduce the setup: - -- Create an organization, get your **Record Key** and **Project Id** at https://app.currents.dev - -- Clone repo -- Install dependencies - - ```sh - npm install - ``` - -- Install browsers - - ```sh - npx playwright install - ``` - -- Set **Record Key** and **Project Id** in `playwright.config.ts` - -- Run tests - - ```sh - npm test - ``` - - Output: - - ```plain - =============================================== - Uploading results to Currents.dev... - Cloud Run Finished: https://app.currents.dev/run/1f2e431c6d46675e - ================================================ - ``` - -Additional resources: - -- Playwright Features on Currents: https://currents.dev/playwright -- Integration Documentation: https://currents.dev/readme/integration-with-playwright/currents-playwright -- CI Build ID Guide: https://currents.dev/readme/guides/ci-build-id - -## Results - -The results are being reported to Currents for more efficient troubleshooting, and monitoring test suite flakiness and performance. - -Currents will collect the following information: - -- console output -- screenshots -- videos -- trace files -- timing -- outcomes -- flaky tests -- error details -- tags for more convenient management of the tests: - -![currents-2024-01-24-15 26 34@2x](https://github.com/currents-dev/currents-playwright-bdd-cucumber-example/assets/1637928/44e38f3c-56f4-469e-884e-71a528ee4dca) - -![currents-2024-01-24-15 29 19@2x](https://github.com/currents-dev/currents-playwright-bdd-cucumber-example/assets/1637928/4ac06f8b-ff38-4f88-8ca0-b3d147d9dd96) - - -- diff --git a/playwright/ci/aws-codebuild/README.md b/playwright/ci/aws-codebuild/README.md index cdb9425..427d2d1 100644 --- a/playwright/ci/aws-codebuild/README.md +++ b/playwright/ci/aws-codebuild/README.md @@ -1,65 +1,118 @@ -# Playwright on AWS CodeBuild - -- **Framework:** `playwright` -- **Use case:** `ci/aws-codebuild` -- **Source repository:** https://github.com/currents-dev/playwright-aws-codebuild-example - -## What this example does - -An example project showing how to run **Playwright tests** on **AWS CodeBuild** (including CodeBuild **batch/matrix** builds) and report results to **Currents** using the Currents Playwright reporter (`@currents/playwright`). - -## How this example is used - -1. **Install & prep** - - Uses Node + Playwright; installs deps via `npm ci`. -2. **Configure Currents** - - Provide `CURRENTS_RECORD_KEY` (recommended via AWS Secrets Manager in CodeBuild). -3. **Run in CodeBuild as a matrix** - - `buildspec.yml` runs a shard per worker using `--shard $WORKER/3` and sets a CI build id. -4. **Playwright config** - - Uses a shared config (`pw.config.shared.ts`) that sets `testDir` to `./basic`, configures artifacts, and starts a local web server for tests. -5. **Reporting** - - `playwright.config.reporter.ts` wires the Currents reporter, and `package.json` includes `@currents/playwright`. - -## What scenarios are included - -- **AWS CodeBuild setup example** - - `buildspec.yml` demonstrating CodeBuild batch/matrix workers + sharding. - - `aws-project-config-output.json` (sample project configuration output). -- **Playwright + Currents reporter setup** - - `playwright.config.reporter.ts` (Currents reporter configuration). - - `pw.config.shared.ts` (shared Playwright settings, artifacts, web server, testDir). - - `basic/` tests directory referenced by config. -- **Local CodeBuild agent run** - - README includes steps and references a helper script for local runs using the CodeBuild local agent image. - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Fix a README link inconsistency** - - README links `buildspec.yml` to a different repo (`currents-dev/aws-codebuild-example`) instead of this repo. (Small but confusing.) -2. **Add a “copy/paste Quickstart”** - - Minimal vars (`CURRENTS_RECORD_KEY`, project id), exact CodeBuild batch settings, and the expected command line for sharding and CI build id. -3. **Add `.env.example` / `codebuild.env.example`** - - Show the minimal env needed to run locally (even if real key should be injected via Secrets Manager in CI). -4. **Add a short “Troubleshooting” section** - - Missing Playwright deps on Linux images, shard count mismatch, CI build id collisions, and where artifacts are stored. -5. **Make `buildspec.yml` easier to skim** - - Add comments explaining the matrix variable (`WORKER`) and the shard formula, plus a note on changing worker count. - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **28** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +# 🎭 Currents - Playwright - AWS CodeBuild + + + +This repository showcases running [Playwright](https://playwright.dev/) tests on AWS CodeBuild in parallel while using [Currents](https://currents.dev) as the reporting dashboard. + +

+ +

+ +## Documentation + +The repo contains a few Playwright tests, one test always fails (intentionally) for demonstration. + +The example [buildspec.yml](https://github.com/currents-dev/aws-codebuild-example/blob/main/buildspec.yml) defines a configuration for running Playwright tests in parallel mode using 3 workers in [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html#batch_build_matrix). The example is designed to be executed as a [batch build](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html). + +## Results + +The results are being reported to Currents for more efficient troubleshooting, and monitoring test suite flakiness and performance. + +Currents will collect the following information: + +- commit details +- console output +- screenshots +- videos +- trace files +- timing +- outcomes +- flaky tests +- error details +- tags for more convenient management of the tests + +The example repository uses an AWS CodeBuild project that runs Playwright tests in parallel on 3 containers using [Playwright Sharding](https://playwright.dev/docs/test-parallel#shard-tests-between-multiple-machines). + +Here's an example of a build that has 1 batch job (1) triggering 3 parallel build jobs (2): + +![currents-2023-11-15-13 23 30@2x](https://github.com/currents-dev/playwright-aws-codebuild-example/assets/1637928/182580b2-f8c4-4ed1-9dd0-2d217c03954c) + +The corresponding run in Currents dashboard: + +https://github.com/currents-dev/playwright-aws-codebuild-example/assets/1637928/9c0bc332-add2-476a-812a-645b9c56ce64 + +## AWS Setup + +Please refer to the [sample output of AWS CodeBuild project configuration](./aws-project-config-output.json) used for this demo. The output was generated using this command: `aws codebuild batch-get-projects --names playwright-currents-example`. Alternatively, follow the instructions below. + +### Obtain Currents Credentials + +- Create an organization, get your **Record Key** and **Project ID** at https://app.currents.dev. +- Update the command in `buildspec.yml` file with the **Project ID**: e.g. `npx pwc --project-id ...` + +### Configure AWS CodeBuild Build Project + +#### Configure `CURRENTS_RECORD_KEY` + +Save the **Record Key** as `CURRENTS_RECORD_KEY` [Environment variable](https://docs.aws.amazon.com/codebuild/latest/userguide/change-project-console.html#change-project-console-environment). It is strongly recommended to use your **Record Key** in a secure secrets storage. Please refer to the [detailed guide](https://www.learnaws.org/2022/11/18/aws-codebuild-secrets-manager/), here is an overview of the steps: + +- Create a new entry in AWS Secrets Manager with the **Record Key**. Please note that the generated secret is a JSON document, you should note the `json_key` of the actual record key value and use it later. +- Get the secret ARN +- Update the Build Project environment variables as follows: + + - Variable name: `CURRENTS_RECORD_KEY` + - Variable value: the ARN of previously created secret + json_key, for example: `:` + +- Update the IAM execution role to allow reading of previously created secret + +#### Configure Source Batch Mode + +- Set the **Project Setting > Edit Source** +- Configure the repository details and the events that should trigger new builds +- Configure **Primary source webhook events > Build Type** to **Batch build** to start 3 parallel workers in [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build). + +## Playwright Parallelization / Sharding + +The `buildspec.yml` file uses [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build) to start 3 containers for running the test in parallel. Each container will have the environment variable `WORKER` set to `1,2,3` correspondingly - we can use it to configure [Playwright Sharding](https://playwright.dev/docs/test-parallel#shard-tests-between-multiple-machines) + +```yml + build-matrix: + dynamic: + buildspec: + - buildspec.yml + env: + variables: + # Create 3 containers, each container will have the environment variable `WORKER` set to `1,2,3` + WORKER: + - 1 + - 2 + - 3 + + # and later, note the use of $WORKER env variable + - npx pwc --project-id bnsqNa --key $CURRENTS_RECORD_KEY --ci-build-id $CODEBUILD_INITIATOR --shard $WORKER/3 +``` + +## CI Build ID for AWS CodeBuild + +The example uses [CODEBUILD_INITIATOR](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html) as a [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id). If you trigger the build manually, the `CODEBUILD_INITIATOR` will be set to the username of the build initiator and you can get warnings after recording multiple results for the same CI build ID. + +When a build is triggered by a push / PR (and a batched build is created), the variable will have a unique ID associated that won' trigger conflict warnings. + +## Using Currents Reporter + +The example uses `pwc` CLI command to run the tests. You can use `npx playwright test` command and configure `@currents/playwright` as a reporter. Please refer to the [documentation](https://currents.dev/readme/integration-with-playwright/currents-playwright#currents-playwright-reporter). + +## Running Locally + +Based on: https://docs.aws.amazon.com/codebuild/latest/userguide/use-codebuild-agent.html + +```sh +curl -O https://raw.githubusercontent.com/aws/aws-codebuild-docker-images/master/local_builds/codebuild_build.sh +chmod +x codebuild_build.sh + +# For MacBook M1 +./codebuild_build.sh -i public.ecr.aws/codebuild/amazonlinux2-aarch64-standard:3.0 -l public.ecr.aws/codebuild/local-builds:aarch64 + +# For Intel +./codebuild_build.sh -i public.ecr.aws/codebuild/amazonlinux2-standard:3.0 +``` diff --git a/playwright/ci/aws-codebuild/README.upstream.md b/playwright/ci/aws-codebuild/README.upstream.md deleted file mode 100644 index 427d2d1..0000000 --- a/playwright/ci/aws-codebuild/README.upstream.md +++ /dev/null @@ -1,118 +0,0 @@ -# 🎭 Currents - Playwright - AWS CodeBuild - - - -This repository showcases running [Playwright](https://playwright.dev/) tests on AWS CodeBuild in parallel while using [Currents](https://currents.dev) as the reporting dashboard. - -

- -

- -## Documentation - -The repo contains a few Playwright tests, one test always fails (intentionally) for demonstration. - -The example [buildspec.yml](https://github.com/currents-dev/aws-codebuild-example/blob/main/buildspec.yml) defines a configuration for running Playwright tests in parallel mode using 3 workers in [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html#batch_build_matrix). The example is designed to be executed as a [batch build](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html). - -## Results - -The results are being reported to Currents for more efficient troubleshooting, and monitoring test suite flakiness and performance. - -Currents will collect the following information: - -- commit details -- console output -- screenshots -- videos -- trace files -- timing -- outcomes -- flaky tests -- error details -- tags for more convenient management of the tests - -The example repository uses an AWS CodeBuild project that runs Playwright tests in parallel on 3 containers using [Playwright Sharding](https://playwright.dev/docs/test-parallel#shard-tests-between-multiple-machines). - -Here's an example of a build that has 1 batch job (1) triggering 3 parallel build jobs (2): - -![currents-2023-11-15-13 23 30@2x](https://github.com/currents-dev/playwright-aws-codebuild-example/assets/1637928/182580b2-f8c4-4ed1-9dd0-2d217c03954c) - -The corresponding run in Currents dashboard: - -https://github.com/currents-dev/playwright-aws-codebuild-example/assets/1637928/9c0bc332-add2-476a-812a-645b9c56ce64 - -## AWS Setup - -Please refer to the [sample output of AWS CodeBuild project configuration](./aws-project-config-output.json) used for this demo. The output was generated using this command: `aws codebuild batch-get-projects --names playwright-currents-example`. Alternatively, follow the instructions below. - -### Obtain Currents Credentials - -- Create an organization, get your **Record Key** and **Project ID** at https://app.currents.dev. -- Update the command in `buildspec.yml` file with the **Project ID**: e.g. `npx pwc --project-id ...` - -### Configure AWS CodeBuild Build Project - -#### Configure `CURRENTS_RECORD_KEY` - -Save the **Record Key** as `CURRENTS_RECORD_KEY` [Environment variable](https://docs.aws.amazon.com/codebuild/latest/userguide/change-project-console.html#change-project-console-environment). It is strongly recommended to use your **Record Key** in a secure secrets storage. Please refer to the [detailed guide](https://www.learnaws.org/2022/11/18/aws-codebuild-secrets-manager/), here is an overview of the steps: - -- Create a new entry in AWS Secrets Manager with the **Record Key**. Please note that the generated secret is a JSON document, you should note the `json_key` of the actual record key value and use it later. -- Get the secret ARN -- Update the Build Project environment variables as follows: - - - Variable name: `CURRENTS_RECORD_KEY` - - Variable value: the ARN of previously created secret + json_key, for example: `:` - -- Update the IAM execution role to allow reading of previously created secret - -#### Configure Source Batch Mode - -- Set the **Project Setting > Edit Source** -- Configure the repository details and the events that should trigger new builds -- Configure **Primary source webhook events > Build Type** to **Batch build** to start 3 parallel workers in [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build). - -## Playwright Parallelization / Sharding - -The `buildspec.yml` file uses [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build) to start 3 containers for running the test in parallel. Each container will have the environment variable `WORKER` set to `1,2,3` correspondingly - we can use it to configure [Playwright Sharding](https://playwright.dev/docs/test-parallel#shard-tests-between-multiple-machines) - -```yml - build-matrix: - dynamic: - buildspec: - - buildspec.yml - env: - variables: - # Create 3 containers, each container will have the environment variable `WORKER` set to `1,2,3` - WORKER: - - 1 - - 2 - - 3 - - # and later, note the use of $WORKER env variable - - npx pwc --project-id bnsqNa --key $CURRENTS_RECORD_KEY --ci-build-id $CODEBUILD_INITIATOR --shard $WORKER/3 -``` - -## CI Build ID for AWS CodeBuild - -The example uses [CODEBUILD_INITIATOR](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html) as a [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id). If you trigger the build manually, the `CODEBUILD_INITIATOR` will be set to the username of the build initiator and you can get warnings after recording multiple results for the same CI build ID. - -When a build is triggered by a push / PR (and a batched build is created), the variable will have a unique ID associated that won' trigger conflict warnings. - -## Using Currents Reporter - -The example uses `pwc` CLI command to run the tests. You can use `npx playwright test` command and configure `@currents/playwright` as a reporter. Please refer to the [documentation](https://currents.dev/readme/integration-with-playwright/currents-playwright#currents-playwright-reporter). - -## Running Locally - -Based on: https://docs.aws.amazon.com/codebuild/latest/userguide/use-codebuild-agent.html - -```sh -curl -O https://raw.githubusercontent.com/aws/aws-codebuild-docker-images/master/local_builds/codebuild_build.sh -chmod +x codebuild_build.sh - -# For MacBook M1 -./codebuild_build.sh -i public.ecr.aws/codebuild/amazonlinux2-aarch64-standard:3.0 -l public.ecr.aws/codebuild/local-builds:aarch64 - -# For Intel -./codebuild_build.sh -i public.ecr.aws/codebuild/amazonlinux2-standard:3.0 -``` diff --git a/playwright/ci/aws-codebuild/source__README.md b/playwright/ci/aws-codebuild/source__README.md deleted file mode 100644 index 427d2d1..0000000 --- a/playwright/ci/aws-codebuild/source__README.md +++ /dev/null @@ -1,118 +0,0 @@ -# 🎭 Currents - Playwright - AWS CodeBuild - - - -This repository showcases running [Playwright](https://playwright.dev/) tests on AWS CodeBuild in parallel while using [Currents](https://currents.dev) as the reporting dashboard. - -

- -

- -## Documentation - -The repo contains a few Playwright tests, one test always fails (intentionally) for demonstration. - -The example [buildspec.yml](https://github.com/currents-dev/aws-codebuild-example/blob/main/buildspec.yml) defines a configuration for running Playwright tests in parallel mode using 3 workers in [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html#batch_build_matrix). The example is designed to be executed as a [batch build](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html). - -## Results - -The results are being reported to Currents for more efficient troubleshooting, and monitoring test suite flakiness and performance. - -Currents will collect the following information: - -- commit details -- console output -- screenshots -- videos -- trace files -- timing -- outcomes -- flaky tests -- error details -- tags for more convenient management of the tests - -The example repository uses an AWS CodeBuild project that runs Playwright tests in parallel on 3 containers using [Playwright Sharding](https://playwright.dev/docs/test-parallel#shard-tests-between-multiple-machines). - -Here's an example of a build that has 1 batch job (1) triggering 3 parallel build jobs (2): - -![currents-2023-11-15-13 23 30@2x](https://github.com/currents-dev/playwright-aws-codebuild-example/assets/1637928/182580b2-f8c4-4ed1-9dd0-2d217c03954c) - -The corresponding run in Currents dashboard: - -https://github.com/currents-dev/playwright-aws-codebuild-example/assets/1637928/9c0bc332-add2-476a-812a-645b9c56ce64 - -## AWS Setup - -Please refer to the [sample output of AWS CodeBuild project configuration](./aws-project-config-output.json) used for this demo. The output was generated using this command: `aws codebuild batch-get-projects --names playwright-currents-example`. Alternatively, follow the instructions below. - -### Obtain Currents Credentials - -- Create an organization, get your **Record Key** and **Project ID** at https://app.currents.dev. -- Update the command in `buildspec.yml` file with the **Project ID**: e.g. `npx pwc --project-id ...` - -### Configure AWS CodeBuild Build Project - -#### Configure `CURRENTS_RECORD_KEY` - -Save the **Record Key** as `CURRENTS_RECORD_KEY` [Environment variable](https://docs.aws.amazon.com/codebuild/latest/userguide/change-project-console.html#change-project-console-environment). It is strongly recommended to use your **Record Key** in a secure secrets storage. Please refer to the [detailed guide](https://www.learnaws.org/2022/11/18/aws-codebuild-secrets-manager/), here is an overview of the steps: - -- Create a new entry in AWS Secrets Manager with the **Record Key**. Please note that the generated secret is a JSON document, you should note the `json_key` of the actual record key value and use it later. -- Get the secret ARN -- Update the Build Project environment variables as follows: - - - Variable name: `CURRENTS_RECORD_KEY` - - Variable value: the ARN of previously created secret + json_key, for example: `:` - -- Update the IAM execution role to allow reading of previously created secret - -#### Configure Source Batch Mode - -- Set the **Project Setting > Edit Source** -- Configure the repository details and the events that should trigger new builds -- Configure **Primary source webhook events > Build Type** to **Batch build** to start 3 parallel workers in [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build). - -## Playwright Parallelization / Sharding - -The `buildspec.yml` file uses [matrix mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build) to start 3 containers for running the test in parallel. Each container will have the environment variable `WORKER` set to `1,2,3` correspondingly - we can use it to configure [Playwright Sharding](https://playwright.dev/docs/test-parallel#shard-tests-between-multiple-machines) - -```yml - build-matrix: - dynamic: - buildspec: - - buildspec.yml - env: - variables: - # Create 3 containers, each container will have the environment variable `WORKER` set to `1,2,3` - WORKER: - - 1 - - 2 - - 3 - - # and later, note the use of $WORKER env variable - - npx pwc --project-id bnsqNa --key $CURRENTS_RECORD_KEY --ci-build-id $CODEBUILD_INITIATOR --shard $WORKER/3 -``` - -## CI Build ID for AWS CodeBuild - -The example uses [CODEBUILD_INITIATOR](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html) as a [CI Build ID](https://currents.dev/readme/guides/cypress-ci-build-id). If you trigger the build manually, the `CODEBUILD_INITIATOR` will be set to the username of the build initiator and you can get warnings after recording multiple results for the same CI build ID. - -When a build is triggered by a push / PR (and a batched build is created), the variable will have a unique ID associated that won' trigger conflict warnings. - -## Using Currents Reporter - -The example uses `pwc` CLI command to run the tests. You can use `npx playwright test` command and configure `@currents/playwright` as a reporter. Please refer to the [documentation](https://currents.dev/readme/integration-with-playwright/currents-playwright#currents-playwright-reporter). - -## Running Locally - -Based on: https://docs.aws.amazon.com/codebuild/latest/userguide/use-codebuild-agent.html - -```sh -curl -O https://raw.githubusercontent.com/aws/aws-codebuild-docker-images/master/local_builds/codebuild_build.sh -chmod +x codebuild_build.sh - -# For MacBook M1 -./codebuild_build.sh -i public.ecr.aws/codebuild/amazonlinux2-aarch64-standard:3.0 -l public.ecr.aws/codebuild/local-builds:aarch64 - -# For Intel -./codebuild_build.sh -i public.ecr.aws/codebuild/amazonlinux2-standard:3.0 -``` diff --git a/playwright/ci/azure-devops/README.md b/playwright/ci/azure-devops/README.md index f9bde4d..7339d05 100644 --- a/playwright/ci/azure-devops/README.md +++ b/playwright/ci/azure-devops/README.md @@ -1,65 +1,45 @@ -# Playwright on Azure DevOps +# 🎭 Currents - Playwright - Azure DevOps -- **Framework:** `playwright` -- **Use case:** `ci/azure-devops` -- **Source repository:** https://github.com/currents-dev/playwright-azure-devops-example +This repository showcases running [Playwright](https://playwright.dev/) tests on Azure DevOps, while using [Currents](https://currents.dev) as the reporting dashboard. -## What this example does +

+ +

-This repository showcases running **Playwright** tests on **Azure DevOps Pipelines** while using **Currents** as the reporting dashboard. -It demonstrates **parallelization with 3 containers** using Azure Pipelines’ **Matrix Execution Strategy** and **Playwright sharding**. +## Documentation -## How this example is used +The repo contains a few Playwright tests with one test that always fails (intentionally). The example configuration files use [Matrix Execution Strategy](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/jobs-job-strategy?view=azure-pipelines#strategy-matrix-maxparallel) to run 3 containers for parallelization. -High-level setup: -1. Create/choose an Azure Pipeline connected to a repo with Playwright tests. -2. Create a Currents org/project and get: - - `CURRENTS_RECORD_KEY` (store as a **secret** in an Azure DevOps **Variable Group**) - - `CURRENTS_PROJECT_ID` (set as an env var in the pipeline). -3. Use `@currents/playwright` + run tests via Currents wrapper (example uses `pwc`) and shard across matrix jobs. +To reproduce the setup: -Example pipeline behavior (from Currents docs): -- Uses a matrix with `shard: 1/3`, `2/3`, `3/3` -- Runs `npx pwc --shard=$(shard)` in `basic/` -- Passes `CURRENTS_PROJECT_ID` and `CURRENTS_RECORD_KEY` to each job. +- Connect a new/existing Azure Pipeline to a repository containing your Playwright tests +- Create an organization, get your **Record Key** and **Project Id** at https://app.currents.dev +- Create or modify an existing [Variable Group](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=yaml), and add a new secret variable called `CURRENTS_RECORD_KEY` with your **Record Key**. +- Include your **Project Id** in an env variable called `CURRENTS_PROJECT_ID` in your pipeline configuration -## What scenarios are included +See the example Azure pipeline configuration: -- **Two Azure pipeline examples**: - - `azure-pipelines.yml` - - `azure-pipelines-reporter.yml` -- A `basic/` folder containing Playwright tests (including **one intentionally failing test**), meant to be run in parallel across 3 containers. -- Documentation pointers and what artifacts Currents collects (console output, screenshots, videos, traces, timing, flaky tests, etc.). +- [azure-pipelines.yml](azure-pipelines.yml) +- [azure-pipelines-reporter.yml](azure-pipelines-reporter.yml) -## How to implement this in your own project +Additional resources: -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. +- Playwright Features on Currents: https://currents.dev/playwright +- Integration Documentation: https://currents.dev/readme/integration-with-playwright/currents-playwright +- CI Build ID Guide: https://currents.dev/readme/guides/cypress-ci-build-id -### Implementation notes from the audit +## Results -1. **Expand/format the README** - - The raw `README.md` is basically a single-line stub; copy/paste UX is bad and it doesn’t include the actual “reproduce” steps that *are* visible on the rendered page. -2. **Remove hardcoded placeholders from docs/snippets** - - The docs example uses a literal `CURRENTS_PROJECT_ID: '3W3DU4'`; make that explicitly a placeholder and recommend a variable/secret instead. -3. **Add a minimal “Quickstart” section** - - Exact steps: create variable group, set secrets, run pipeline, “what success looks like” in Currents. -4. **Make the two pipeline styles explicit** - - Explain what `azure-pipelines.yml` vs `azure-pipelines-reporter.yml` demonstrate (e.g., `pwc` wrapper vs reporter-only approach), and when to choose which. (Right now you have the files but not a clear comparison in README.) -5. **Make code/config files human-readable** - - Several files in this org’s examples tend to be minified into single-line blobs; ensure YAML/JSON/TS files are properly formatted so users can learn from diffs and copy sections cleanly. +The results are being reported to Currents for more efficient troubleshooting, and monitoring test suite flakiness and performance. -## Source markdown copied into this folder +Currents will collect the following information: -- [`source__CODE_OF_CONDUCT.md`](source__CODE_OF_CONDUCT.md) -- [`source__README.md`](source__README.md) -- [`source__SECURITY.md`](source__SECURITY.md) - -## Repository content copied into this folder - -- Total tracked files copied: **31** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +- console output +- screenshots +- videos +- trace files +- timing +- outcomes +- flaky tests +- error details +- tags for more convenient management of the tests diff --git a/playwright/ci/azure-devops/README.upstream.md b/playwright/ci/azure-devops/README.upstream.md deleted file mode 100644 index 7339d05..0000000 --- a/playwright/ci/azure-devops/README.upstream.md +++ /dev/null @@ -1,45 +0,0 @@ -# 🎭 Currents - Playwright - Azure DevOps - -This repository showcases running [Playwright](https://playwright.dev/) tests on Azure DevOps, while using [Currents](https://currents.dev) as the reporting dashboard. - -

- -

- -## Documentation - -The repo contains a few Playwright tests with one test that always fails (intentionally). The example configuration files use [Matrix Execution Strategy](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/jobs-job-strategy?view=azure-pipelines#strategy-matrix-maxparallel) to run 3 containers for parallelization. - -To reproduce the setup: - -- Connect a new/existing Azure Pipeline to a repository containing your Playwright tests -- Create an organization, get your **Record Key** and **Project Id** at https://app.currents.dev -- Create or modify an existing [Variable Group](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=yaml), and add a new secret variable called `CURRENTS_RECORD_KEY` with your **Record Key**. -- Include your **Project Id** in an env variable called `CURRENTS_PROJECT_ID` in your pipeline configuration - -See the example Azure pipeline configuration: - -- [azure-pipelines.yml](azure-pipelines.yml) -- [azure-pipelines-reporter.yml](azure-pipelines-reporter.yml) - -Additional resources: - -- Playwright Features on Currents: https://currents.dev/playwright -- Integration Documentation: https://currents.dev/readme/integration-with-playwright/currents-playwright -- CI Build ID Guide: https://currents.dev/readme/guides/cypress-ci-build-id - -## Results - -The results are being reported to Currents for more efficient troubleshooting, and monitoring test suite flakiness and performance. - -Currents will collect the following information: - -- console output -- screenshots -- videos -- trace files -- timing -- outcomes -- flaky tests -- error details -- tags for more convenient management of the tests diff --git a/playwright/ci/azure-devops/source__README.md b/playwright/ci/azure-devops/source__README.md deleted file mode 100644 index 7339d05..0000000 --- a/playwright/ci/azure-devops/source__README.md +++ /dev/null @@ -1,45 +0,0 @@ -# 🎭 Currents - Playwright - Azure DevOps - -This repository showcases running [Playwright](https://playwright.dev/) tests on Azure DevOps, while using [Currents](https://currents.dev) as the reporting dashboard. - -

- -

- -## Documentation - -The repo contains a few Playwright tests with one test that always fails (intentionally). The example configuration files use [Matrix Execution Strategy](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/jobs-job-strategy?view=azure-pipelines#strategy-matrix-maxparallel) to run 3 containers for parallelization. - -To reproduce the setup: - -- Connect a new/existing Azure Pipeline to a repository containing your Playwright tests -- Create an organization, get your **Record Key** and **Project Id** at https://app.currents.dev -- Create or modify an existing [Variable Group](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=yaml), and add a new secret variable called `CURRENTS_RECORD_KEY` with your **Record Key**. -- Include your **Project Id** in an env variable called `CURRENTS_PROJECT_ID` in your pipeline configuration - -See the example Azure pipeline configuration: - -- [azure-pipelines.yml](azure-pipelines.yml) -- [azure-pipelines-reporter.yml](azure-pipelines-reporter.yml) - -Additional resources: - -- Playwright Features on Currents: https://currents.dev/playwright -- Integration Documentation: https://currents.dev/readme/integration-with-playwright/currents-playwright -- CI Build ID Guide: https://currents.dev/readme/guides/cypress-ci-build-id - -## Results - -The results are being reported to Currents for more efficient troubleshooting, and monitoring test suite flakiness and performance. - -Currents will collect the following information: - -- console output -- screenshots -- videos -- trace files -- timing -- outcomes -- flaky tests -- error details -- tags for more convenient management of the tests diff --git a/playwright/ci/circleci/README.md b/playwright/ci/circleci/README.md index 4cccff4..99cd197 100644 --- a/playwright/ci/circleci/README.md +++ b/playwright/ci/circleci/README.md @@ -1,60 +1,13 @@ -# Playwright on CircleCI +# Currents.dev - CircleCI Playwright Example -- **Framework:** `playwright` -- **Use case:** `ci/circleci` -- **Source repository:** https://github.com/currents-dev/circleci-pw-example +This is an example repository that showcases running Playwright tests using 3 parallel [CircleCI](https://circleci.com) containers with [Currents.dev](https://currents.dev). -## What this example does +The example [config file](.circleci/config.yml): -An example showing how to run **Playwright tests on CircleCI using 3 parallel containers** and report results to **Currents** (via `pwc` / `@currents/playwright`). +- uses [Test CLI commands](https://playwright.dev/docs/test-cli) to run `@currents/playwright` for recording test results and parallelization with [Currents.dev](https://currents.dev) -## How this example is used +- Set the `CURRENTS_PROJECT_ID` [Environment variable](https://circleci.com/docs/2.0/env-vars/) - obtain the project id from [Currents.dev](https://app.currents.dev) -- CircleCI config enables **parallelism: 3** and uses CircleCI’s shard indexes to compute the Playwright shard: - - `SHARD="$((${CIRCLE_NODE_INDEX}+1))"` and `--shard=${SHARD}/${CIRCLE_NODE_TOTAL}` when running `npx pwc ...` -- Users set: - - `CURRENTS_RECORD_KEY` (recommended via CircleCI contexts) - - `CURRENTS_PROJECT_ID` (from Currents project settings) -- The repo includes the CircleCI config file at `.circleci/config.yml`. +- Use CLI arguments to customize your Playwright runs, e.g.: `npx pwc --key ` -## What scenarios are included - -- **CircleCI parallel Playwright run** - - `.circleci/config.yml` demonstrating 3-way parallelization + sharding. -- **Playwright project scaffolding** - - `playwright.config.ts`, `tests/`, and a Node project (`package.json`) exist in the repo. -- **README explanation** - - Repo README describes the goal and points to the config file and `pwc` usage. -- **Official docs cross-link** - - Currents docs explicitly reference this repo as the CircleCI Playwright example. - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Pretty-print the files** - - The raw `README.md`, `.circleci/config.yml`, and `package.json` render as single-line blobs, which makes copying/editing painful. -2. **Stop hardcoding `--project-id` in docs/snippets** - - The docs snippet uses a concrete project id (`bnsqNa`) as an example; make it very explicit it’s a placeholder and recommend `CURRENTS_PROJECT_ID` via env/context. -3. **Add a “Quickstart” with exact steps** - - (1) create project → (2) set CircleCI context vars → (3) run pipeline → (4) where to see results in Currents. -4. **Fail fast on missing env** - - If `CURRENTS_RECORD_KEY` / `CURRENTS_PROJECT_ID` are missing, print a clear error and exit (instead of running a confusing “empty” run). -5. **Add caching + `npm ci`** - - Show recommended CircleCI caching for node modules and use `npm ci` for deterministic installs (especially for examples people will copy). - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **12** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +- Create an organization, get your record key at [Currents.dev](https://app.currents.dev) and set [Environment variable](https://circleci.com/docs/2.0/env-vars/) `CURRENTS_RECORD_KEY` diff --git a/playwright/ci/circleci/README.upstream.md b/playwright/ci/circleci/README.upstream.md deleted file mode 100644 index 99cd197..0000000 --- a/playwright/ci/circleci/README.upstream.md +++ /dev/null @@ -1,13 +0,0 @@ -# Currents.dev - CircleCI Playwright Example - -This is an example repository that showcases running Playwright tests using 3 parallel [CircleCI](https://circleci.com) containers with [Currents.dev](https://currents.dev). - -The example [config file](.circleci/config.yml): - -- uses [Test CLI commands](https://playwright.dev/docs/test-cli) to run `@currents/playwright` for recording test results and parallelization with [Currents.dev](https://currents.dev) - -- Set the `CURRENTS_PROJECT_ID` [Environment variable](https://circleci.com/docs/2.0/env-vars/) - obtain the project id from [Currents.dev](https://app.currents.dev) - -- Use CLI arguments to customize your Playwright runs, e.g.: `npx pwc --key ` - -- Create an organization, get your record key at [Currents.dev](https://app.currents.dev) and set [Environment variable](https://circleci.com/docs/2.0/env-vars/) `CURRENTS_RECORD_KEY` diff --git a/playwright/ci/circleci/source__README.md b/playwright/ci/circleci/source__README.md deleted file mode 100644 index 99cd197..0000000 --- a/playwright/ci/circleci/source__README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Currents.dev - CircleCI Playwright Example - -This is an example repository that showcases running Playwright tests using 3 parallel [CircleCI](https://circleci.com) containers with [Currents.dev](https://currents.dev). - -The example [config file](.circleci/config.yml): - -- uses [Test CLI commands](https://playwright.dev/docs/test-cli) to run `@currents/playwright` for recording test results and parallelization with [Currents.dev](https://currents.dev) - -- Set the `CURRENTS_PROJECT_ID` [Environment variable](https://circleci.com/docs/2.0/env-vars/) - obtain the project id from [Currents.dev](https://app.currents.dev) - -- Use CLI arguments to customize your Playwright runs, e.g.: `npx pwc --key ` - -- Create an organization, get your record key at [Currents.dev](https://app.currents.dev) and set [Environment variable](https://circleci.com/docs/2.0/env-vars/) `CURRENTS_RECORD_KEY` diff --git a/playwright/ci/jenkins/jenkins-last-failed/README.md b/playwright/ci/jenkins/jenkins-last-failed/README.md index d16fd1c..746c0db 100644 --- a/playwright/ci/jenkins/jenkins-last-failed/README.md +++ b/playwright/ci/jenkins/jenkins-last-failed/README.md @@ -1,83 +1,18 @@ -# Playwright on Jenkins (Last Failed & Orchestration) +# Currents.dev - Jenkins Playwright Last Failed Example -- **Framework:** `playwright` -- **Use case:** `ci/jenkins` -- **Source repository:** https://github.com/currents-dev/jenkins-last-failed +This is an example repository that showcases using [Currents.dev](https://currents.dev) for running Playwright tests on Jenkins with the last failed flag. -## What this example does -An example repo showing how to run **Playwright on Jenkins** and use Currents’ **`--last-failed`** capability (rerun only previously failed tests), supporting both: -- native shards (`pwc --shard=...`) -- Currents orchestration (`pwc-p`) -- Docker-based execution (via `Jenkinsfile.docker`) +- Note: get your record key from [Currents.dev](https://app.currents.dev) and set [Jenkins credential](https://www.jenkins.io/doc/book/security/credentials/) variable `CURRENTS_RECORD_KEY` -## How this example is used +- Note: set the `CURRENTS_PROJECT_ID` [Jenkins credential](https://www.jenkins.io/doc/book/security/credentials/) variable - obtain the project id from [Currents.dev](https://app.currents.dev) -- You configure Jenkins credentials: - - `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`, and `CURRENTS_API_KEY`. -- The `Jenkinsfile` defines parameters: - - `CI_BUILD_ID` (if set, it reruns last-failed for that run) - - `IS_ORCHESTRATION` (choose orchestration vs shards). -- The `Jenkinsfile.docker` provides a simpler, containerized example: - - Uses `mcr.microsoft.com/playwright` image - - Runs 2 parallel shards - - Demonstrates basic Currents integration in Docker -- If `CI_BUILD_ID != 'none'`, it first generates a `.last-run.json` file by calling: - - `npx currents api get-run --api-key ... --project-id ... --ci-build-id ... --pw-last-run --output .last-run.json` - This matches Currents docs: `--last-failed` needs an API key and uses `@currents/cmd` to generate `.last-run.json` for the target CI build id. -- It then runs either: - - **Shards:** `npx pwc --shard=i/N` (or `--last-failed --output ...`) across `TOTAL_SHARDS` in parallel - - **Orchestration:** `npx pwc-p` (or `--last-failed --output ...`) across `PARALLEL_JOBS` in parallel +- Note: set the `CURRENTS_API_KEY` [Jenkins credential](https://www.jenkins.io/doc/book/security/credentials/) variable - obtain the API Key from [Currents.dev](https://app.currents.dev) -## What scenarios are included -- **Jenkins Pipeline** example with: - - parameters (CI_BUILD_ID, orchestration toggle) - - dependency install + Playwright install - - generation of `.last-run.json` from Currents API - - parallel execution strategy for shards vs orchestration - - copying `.last-run.json` into per-shard/per-parallel output folders. -- **Playwright project config**: - - `testDir: "./tests"`, artifacts enabled (`trace/video/screenshot`), outputDir `test-results/`, Currents reporter. -- **Node deps** include: - - `@currents/cmd` and `@currents/playwright` plus Playwright packages. -- `tests/` directory exists (the suite the pipeline runs). +# Jenkins Setup -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Remove hardcoded Currents keys from `playwright.config.ts`** - - It currently hardcodes `recordKey` and `projectId` in source. Use env vars and fail-fast if missing (and keep secrets out of git). -2. **Rewrite the README as a real setup guide** - - Right now it’s a short note + plugin list, and it’s also hard to read in raw form. Add: - - required Jenkins credentials IDs - - how to trigger “normal run” vs “last-failed run” - - how to find the CI Build ID to paste into `CI_BUILD_ID`. -3. **Clarify the CI build id logic** - - `CURRENTS_CI_BUILD_ID` is set to `reporter-${JOB_NAME}-${BUILD_ID}-${BUILD_NUMBER}`, but the “last failed” lookup uses the user-supplied `CI_BUILD_ID`. Explain that relationship and show an example of a value that should be used. -4. **Make shard/orchestration counts configurable** - - `TOTAL_SHARDS=3`, `PARALLEL_JOBS=4` are hardcoded. Expose as Jenkins parameters (with defaults) and document how to choose them. -5. **Add artifact archiving** - - The pipeline writes outputs under `test-results/...`; add a post step to archive these so users can view artifacts directly in Jenkins. -6. **Provide a “local reproduction” path** - - Minimal steps to run: - - `npx pwc --shard=1/3` and - - `npx currents api get-run ... --pw-last-run` + `npx pwc --last-failed ...` - so people can validate before wiring Jenkins. - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **11** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +The following plugins are needed (You can find it with the same names): +- Github Plugin +- Pipeline Plugin +- SCM Api Plugin \ No newline at end of file diff --git a/playwright/ci/jenkins/jenkins-last-failed/README.upstream.md b/playwright/ci/jenkins/jenkins-last-failed/README.upstream.md deleted file mode 100644 index 746c0db..0000000 --- a/playwright/ci/jenkins/jenkins-last-failed/README.upstream.md +++ /dev/null @@ -1,18 +0,0 @@ -# Currents.dev - Jenkins Playwright Last Failed Example - -This is an example repository that showcases using [Currents.dev](https://currents.dev) for running Playwright tests on Jenkins with the last failed flag. - - -- Note: get your record key from [Currents.dev](https://app.currents.dev) and set [Jenkins credential](https://www.jenkins.io/doc/book/security/credentials/) variable `CURRENTS_RECORD_KEY` - -- Note: set the `CURRENTS_PROJECT_ID` [Jenkins credential](https://www.jenkins.io/doc/book/security/credentials/) variable - obtain the project id from [Currents.dev](https://app.currents.dev) - -- Note: set the `CURRENTS_API_KEY` [Jenkins credential](https://www.jenkins.io/doc/book/security/credentials/) variable - obtain the API Key from [Currents.dev](https://app.currents.dev) - - -# Jenkins Setup - -The following plugins are needed (You can find it with the same names): -- Github Plugin -- Pipeline Plugin -- SCM Api Plugin \ No newline at end of file diff --git a/playwright/ci/jenkins/jenkins-last-failed/source__README.md b/playwright/ci/jenkins/jenkins-last-failed/source__README.md deleted file mode 100644 index 746c0db..0000000 --- a/playwright/ci/jenkins/jenkins-last-failed/source__README.md +++ /dev/null @@ -1,18 +0,0 @@ -# Currents.dev - Jenkins Playwright Last Failed Example - -This is an example repository that showcases using [Currents.dev](https://currents.dev) for running Playwright tests on Jenkins with the last failed flag. - - -- Note: get your record key from [Currents.dev](https://app.currents.dev) and set [Jenkins credential](https://www.jenkins.io/doc/book/security/credentials/) variable `CURRENTS_RECORD_KEY` - -- Note: set the `CURRENTS_PROJECT_ID` [Jenkins credential](https://www.jenkins.io/doc/book/security/credentials/) variable - obtain the project id from [Currents.dev](https://app.currents.dev) - -- Note: set the `CURRENTS_API_KEY` [Jenkins credential](https://www.jenkins.io/doc/book/security/credentials/) variable - obtain the API Key from [Currents.dev](https://app.currents.dev) - - -# Jenkins Setup - -The following plugins are needed (You can find it with the same names): -- Github Plugin -- Pipeline Plugin -- SCM Api Plugin \ No newline at end of file diff --git a/playwright/ci/nx/README.md b/playwright/ci/nx/README.md index 0fe7222..5485109 100644 --- a/playwright/ci/nx/README.md +++ b/playwright/ci/nx/README.md @@ -1,83 +1,116 @@ -# Playwright in Nx Monorepo +# Currents Playwright NX Example -- **Framework:** `playwright` -- **Use case:** `workspace/nx` -- **Source repository:** https://github.com/currents-dev/currents-playwright-nx-example +This repository shows how to use NX + Playwright with Currents. -## What this example does +## Setup -An example Nx monorepo showing how to run **Playwright E2E tests in Nx** while reporting results to **Currents** using `@currents/playwright` as the Playwright reporter. +```sh +npm i -g nx@latest +npm i +``` -## How this example is used +## Run -### Standard Nx E2E (2 projects in parallel) -Run Nx `run-many` for the `e2e` target across multiple projects, passing Currents env vars: -- `CURRENTS_RECORD_KEY` -- `CURRENTS_PROJECT_ID` -- `CURRENTS_CI_BUILD_ID` +The repo has two projects and each has its own tests. -Command shown in README: -- `nx run-many -t e2e --parallel=2 --verbose` +```sh +CURRENTS_RECORD_KEY=recordkey \ +CURRENTS_PROJECT_ID=projectid \ +CURRENTS_CI_BUILD_ID=`date +%s` \ +nx run-many -t e2e --parallel=2 --verbose -Each project’s `e2e` target uses the Nx Playwright executor and overrides the output directory: -- executor: `@nx/playwright:playwright` -- output: `{workspaceRoot}/playwright-report/{projectName}` -- config: `{projectRoot}/playwright.config.ts` +# ... -### Single-project orchestration (pwc-p) -There’s a third project (`e2e-03`) that uses a different Nx target (`or8n`) that runs `npx pwc-p` (Currents orchestration command) via `nx:run-commands`. + NX Running target e2e for 2 projects -README command: -- `nx run-many -t or8n` (single project, no `--parallel` needed) + → Executing 2/2 remaining tasks in parallel... -A GitHub Actions workflow example exists for running the `or8n` target across shards. + ⠙ nx run e2e-01:e2e + ⠙ nx run e2e-02:e2e -## What scenarios are included +# ... -- **Nx + Playwright + Currents reporter wiring** - - Root reporter: `currentsReporter(currents.config)` and exported `reporter`. - - Per-project Playwright configs use `nxE2EPreset(__filename)` and import the shared `reporter`. -- **Multiple Nx Playwright projects** - - `apps/e2e-01` + `apps/e2e-02` with `e2e` target configured via `@nx/playwright:playwright`. - - `apps/e2e-03` with `or8n` target running `npx pwc-p`. -- **Output directory pattern** - - Example output folder layout under `playwright-report/{projectName}` including `.last-run.json`. -- **“Last failed” passthrough** - - Shows Nx passes unknown args to targets (e.g., `--last-failed`). -- **GitHub Actions workflow for orchestration** - - `.github/workflows/or8n.yml` runs `nx run-many -t or8n` with a shard matrix. + NX Ran target e2e for 2 projects (8s) -## How to implement this in your own project + ✔ 1/2 succeeded [0 read from cache] -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. + ✖ 1/2 targets failed, including the following: -### Implementation notes from the audit + - nx run e2e-01:e2e +``` -1. **Reformat the files for readability** - - Many files render as single-line (README, JSON, configs). Re-indent + add code fences so the repo is skimmable. -2. **Make CI config “production-safe” by default** - - The workflow sets `CURRENTS_API_URL: https://cy-staging.currents.dev`. Make this optional (documented), default to production, or use a repo variable. -3. **Add `.env.example` + a single “Quickstart” block** - - Explicitly list required env vars and provide copy/paste commands for: - - `nx run-many -t e2e ...` - - `nx run-many -t or8n ...` -4. **Explain what `pwc-p` is and when to use it** - - README mentions it briefly; add a short “Why orchestration vs Nx/Playwright sharding” section and link to Currents Nx docs. -5. **Add a second workflow for the “normal” e2e target** - - Right now the repo explicitly references `or8n.yml` for GitHub Actions; add a `e2e.yml` to show the standard `@nx/playwright:playwright` flow too. -6. **Add minimal npm scripts** - - Even if Nx is the focus, scripts like `npm run e2e` / `npm run or8n` reduce friction for newcomers. (Current `package.json` has no scripts.) +### Output directory -## Source markdown copied into this folder +Playwright output directory is set in `project.json` > `targets.e2e.options.output`, for example: -- [`source__README.md`](source__README.md) +```json + "targets": { + "e2e": { + "executor": "@nx/playwright:playwright", + "options": { + "skipInstall": true, + "output": "{workspaceRoot}/playwright-report/{projectName}", + "config": "{projectRoot}/playwright.config.ts" + } + } + } +``` -## Repository content copied into this folder +After running the tests, results will appear as: -- Total tracked files copied: **34** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +```plain +playwright-report/ +├── e2e-01/ +│ └── .last-run.json +└── e2e-02/ + └── .last-run.json +``` + +ℹ️ `playwright.config.ts` for each project use `nxE2EPreset` - it sets a different `output` directory, but `project.json:output` overrides it. + +### Last Failed + +nx passes down unrecognized arguments to the target command, for example + +```sh +nx run-many -t e2e --parallel=2 --verbose --last-failed +# ... + + NX Ran target e2e for 2 projects (7s) + + With additional flags: + --last-failed=true +# ... + NX Ran target e2e for 2 projects (7s) + + With additional flags: + --last-failed=true + + ✔ 1/2 succeeded [0 read from cache] + + ✖ 1/2 targets failed, including the following: + + - nx run e2e-01:e2e +``` + +## Single project orchestration + +The project named `e2e-03` has a different target than the other two projects. The target is `or8n` +This target project executes `pwc-p` command. When using it in multiple machines it will execute in parallel the tests of this project. + +```sh +CURRENTS_RECORD_KEY=recordkey \ +CURRENTS_PROJECT_ID=projectid \ +CURRENTS_CI_BUILD_ID=`date +%s` \ +nx run-many -t or8n + +# ... + + NX Running target or8n for 1 project + + ⠙ nx run e2e-03:or8n +``` + +The `parallel` flag is no longer needed as it is running a single nx project. + +The `or8n.yml` file has an example for running it in Github actions. diff --git a/playwright/ci/nx/README.upstream.md b/playwright/ci/nx/README.upstream.md deleted file mode 100644 index 5485109..0000000 --- a/playwright/ci/nx/README.upstream.md +++ /dev/null @@ -1,116 +0,0 @@ -# Currents Playwright NX Example - -This repository shows how to use NX + Playwright with Currents. - -## Setup - -```sh -npm i -g nx@latest -npm i -``` - -## Run - -The repo has two projects and each has its own tests. - -```sh -CURRENTS_RECORD_KEY=recordkey \ -CURRENTS_PROJECT_ID=projectid \ -CURRENTS_CI_BUILD_ID=`date +%s` \ -nx run-many -t e2e --parallel=2 --verbose - -# ... - - NX Running target e2e for 2 projects - - → Executing 2/2 remaining tasks in parallel... - - ⠙ nx run e2e-01:e2e - ⠙ nx run e2e-02:e2e - -# ... - - NX Ran target e2e for 2 projects (8s) - - ✔ 1/2 succeeded [0 read from cache] - - ✖ 1/2 targets failed, including the following: - - - nx run e2e-01:e2e -``` - -### Output directory - -Playwright output directory is set in `project.json` > `targets.e2e.options.output`, for example: - -```json - "targets": { - "e2e": { - "executor": "@nx/playwright:playwright", - "options": { - "skipInstall": true, - "output": "{workspaceRoot}/playwright-report/{projectName}", - "config": "{projectRoot}/playwright.config.ts" - } - } - } -``` - -After running the tests, results will appear as: - -```plain -playwright-report/ -├── e2e-01/ -│ └── .last-run.json -└── e2e-02/ - └── .last-run.json -``` - -ℹ️ `playwright.config.ts` for each project use `nxE2EPreset` - it sets a different `output` directory, but `project.json:output` overrides it. - -### Last Failed - -nx passes down unrecognized arguments to the target command, for example - -```sh -nx run-many -t e2e --parallel=2 --verbose --last-failed -# ... - - NX Ran target e2e for 2 projects (7s) - - With additional flags: - --last-failed=true -# ... - NX Ran target e2e for 2 projects (7s) - - With additional flags: - --last-failed=true - - ✔ 1/2 succeeded [0 read from cache] - - ✖ 1/2 targets failed, including the following: - - - nx run e2e-01:e2e -``` - -## Single project orchestration - -The project named `e2e-03` has a different target than the other two projects. The target is `or8n` -This target project executes `pwc-p` command. When using it in multiple machines it will execute in parallel the tests of this project. - -```sh -CURRENTS_RECORD_KEY=recordkey \ -CURRENTS_PROJECT_ID=projectid \ -CURRENTS_CI_BUILD_ID=`date +%s` \ -nx run-many -t or8n - -# ... - - NX Running target or8n for 1 project - - ⠙ nx run e2e-03:or8n -``` - -The `parallel` flag is no longer needed as it is running a single nx project. - -The `or8n.yml` file has an example for running it in Github actions. diff --git a/playwright/ci/nx/source__README.md b/playwright/ci/nx/source__README.md deleted file mode 100644 index 5485109..0000000 --- a/playwright/ci/nx/source__README.md +++ /dev/null @@ -1,116 +0,0 @@ -# Currents Playwright NX Example - -This repository shows how to use NX + Playwright with Currents. - -## Setup - -```sh -npm i -g nx@latest -npm i -``` - -## Run - -The repo has two projects and each has its own tests. - -```sh -CURRENTS_RECORD_KEY=recordkey \ -CURRENTS_PROJECT_ID=projectid \ -CURRENTS_CI_BUILD_ID=`date +%s` \ -nx run-many -t e2e --parallel=2 --verbose - -# ... - - NX Running target e2e for 2 projects - - → Executing 2/2 remaining tasks in parallel... - - ⠙ nx run e2e-01:e2e - ⠙ nx run e2e-02:e2e - -# ... - - NX Ran target e2e for 2 projects (8s) - - ✔ 1/2 succeeded [0 read from cache] - - ✖ 1/2 targets failed, including the following: - - - nx run e2e-01:e2e -``` - -### Output directory - -Playwright output directory is set in `project.json` > `targets.e2e.options.output`, for example: - -```json - "targets": { - "e2e": { - "executor": "@nx/playwright:playwright", - "options": { - "skipInstall": true, - "output": "{workspaceRoot}/playwright-report/{projectName}", - "config": "{projectRoot}/playwright.config.ts" - } - } - } -``` - -After running the tests, results will appear as: - -```plain -playwright-report/ -├── e2e-01/ -│ └── .last-run.json -└── e2e-02/ - └── .last-run.json -``` - -ℹ️ `playwright.config.ts` for each project use `nxE2EPreset` - it sets a different `output` directory, but `project.json:output` overrides it. - -### Last Failed - -nx passes down unrecognized arguments to the target command, for example - -```sh -nx run-many -t e2e --parallel=2 --verbose --last-failed -# ... - - NX Ran target e2e for 2 projects (7s) - - With additional flags: - --last-failed=true -# ... - NX Ran target e2e for 2 projects (7s) - - With additional flags: - --last-failed=true - - ✔ 1/2 succeeded [0 read from cache] - - ✖ 1/2 targets failed, including the following: - - - nx run e2e-01:e2e -``` - -## Single project orchestration - -The project named `e2e-03` has a different target than the other two projects. The target is `or8n` -This target project executes `pwc-p` command. When using it in multiple machines it will execute in parallel the tests of this project. - -```sh -CURRENTS_RECORD_KEY=recordkey \ -CURRENTS_PROJECT_ID=projectid \ -CURRENTS_CI_BUILD_ID=`date +%s` \ -nx run-many -t or8n - -# ... - - NX Running target or8n for 1 project - - ⠙ nx run e2e-03:or8n -``` - -The `parallel` flag is no longer needed as it is running a single nx project. - -The `or8n.yml` file has an example for running it in Github actions. diff --git a/playwright/code-coverage/instrumented-coverage/README.md b/playwright/code-coverage/instrumented-coverage/README.md index c630619..08eb870 100644 --- a/playwright/code-coverage/instrumented-coverage/README.md +++ b/playwright/code-coverage/instrumented-coverage/README.md @@ -1,74 +1,26 @@ -# Playwright Instrumented Coverage +# Currents Coverage with Playwright -- **Framework:** `playwright` -- **Use case:** `features/coverage` -- **Source repository:** https://github.com/currents-dev/currents-playwright-coverage-example +Playwright [code coverage](https://docs.currents.dev/guides/coverage) for Currents. -## What this example does +This is a simple NextJS application. It uses Babel and Instanbul for instrumentating the code, then Playwright runs a set of e2e tests and send the results to Currents for post-processing. -A Next.js + Playwright example that demonstrates **collecting code coverage** (instrumented via Babel/Istanbul) and **sending coverage + test results to Currents** for post-processing. - -## How this example is used - -- Install deps: `npm install`. -- Provide Currents credentials (recommended via env vars): - - `CURRENTS_RECORD_KEY` - - `CURRENTS_PROJECT_ID` -- Run one of the provided scripts: - - `npm test` → starts Next dev server + runs `playwright test`. - - `npm run test:e2e` → starts Next dev server + runs `pwc`. - - `npm run test:e2e:pwc-p` → starts Next dev server + runs `pwc-p` (orchestrated). -- Coverage plumbing: - - App is instrumented through Babel with `babel-plugin-istanbul`. - - Playwright config uses Currents reporter + Currents fixtures config (`currentsConfigOptions`) and enables coverage with `coverage: { projects: true }`. - - Docs describe using Currents “coverage fixtures” in Playwright tests to attach coverage to runs. - -## What scenarios are included - -- **Runnable scripts** showing 3 execution modes: - - `playwright`, `pwc`, and `pwc-p` (all via `start-server-and-test` against `http://localhost:3000`). -- **Instrumentation configs** - - `babel.config.js` uses the `istanbul` plugin. - - `nyc.config.js` shows a minimal NYC config (exclude Next build output, report formats). -- **Currents + Playwright wiring** - - `playwright.config.ts` includes `dotenv` loading, Currents reporter, and Currents coverage config. -- **Project structure indicating what’s included** - - Next.js app folders (`app/`, `content/`, `public/`) plus `tests/e2e/` in the repo tree. -- **Docs-backed reference** - - Currents documentation points to this repo as the “NextJS + Babel Example” for Playwright coverage. - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit +![currents-2024-11-21-16 21 20@2x](https://github.com/user-attachments/assets/2e2fb1da-31fa-43a7-b84e-670ce1b88c09) -1. **Stop telling users to edit `playwright.config.ts` for secrets** - - README says “Update `playwright.config.ts` with record key and project id”, but the config already supports env vars; switch README to env-only and add `.env.example`. -2. **Fail fast instead of using placeholders** - - Current defaults fall back to `"your-record-key"` / `"your-project-id"`, which can silently send confusing runs; throw a clear error if missing. -3. **Reformat files** - - Several key files are committed as single-line blobs (config/scripts), making copying/learning harder; pretty-print `playwright.config.ts`, `package.json`, etc. -4. **Add a “Coverage flow” section (local + CI)** - - Explicitly document: where coverage is collected (`window.__coverage__` / fixtures), what gets uploaded, and how to view coverage in Currents (link the docs section). -5. **Provide a CI workflow** - - Add a minimal GitHub Actions example that runs `npm test` (or `test:e2e:pwc-p`) with required secrets; most users will copy from CI-first examples. -6. **Clarify browser expectations** - - The config runs Chromium/Firefox/WebKit; coverage instrumentation can behave differently across browsers—call out the intended supported matrix (or restrict to the supported one for coverage if needed). +## Setup -## Source markdown copied into this folder +- Install dependencies with `npm install` +- Update `playwright.config.ts` with Currents [record key](https://docs.currents.dev/guides/record-key) and [project id](https://docs.currents.dev/dashboard/projects/project-settings) +- Run `npm run test` for running tests, behind the scenes: -- [`source__README.md`](source__README.md) + - starts NextJS in dev mode + - runs playwright tests + - send coverage reports to Currents for post-processing -## Repository content copied into this folder +## Examples -- Total tracked files copied: **55** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +- Run `npm run test:e2e` for using [`pwc`](https://docs.currents.dev/getting-started/playwright/you-first-playwright-run#using-the-cli) command +- Run `npm run test:e2e:pwc-p` for [orchestrated](https://docs.currents.dev/guides/parallelization-guide/pw-parallelization/playwright-orchestration) runs +## Licence -![currents-2024-11-21-16 21 20@2x](https://github.com/user-attachments/assets/2e2fb1da-31fa-43a7-b84e-670ce1b88c09) +MIT License diff --git a/playwright/code-coverage/instrumented-coverage/README.upstream.md b/playwright/code-coverage/instrumented-coverage/README.upstream.md deleted file mode 100644 index 08eb870..0000000 --- a/playwright/code-coverage/instrumented-coverage/README.upstream.md +++ /dev/null @@ -1,26 +0,0 @@ -# Currents Coverage with Playwright - -Playwright [code coverage](https://docs.currents.dev/guides/coverage) for Currents. - -This is a simple NextJS application. It uses Babel and Instanbul for instrumentating the code, then Playwright runs a set of e2e tests and send the results to Currents for post-processing. - -![currents-2024-11-21-16 21 20@2x](https://github.com/user-attachments/assets/2e2fb1da-31fa-43a7-b84e-670ce1b88c09) - -## Setup - -- Install dependencies with `npm install` -- Update `playwright.config.ts` with Currents [record key](https://docs.currents.dev/guides/record-key) and [project id](https://docs.currents.dev/dashboard/projects/project-settings) -- Run `npm run test` for running tests, behind the scenes: - - - starts NextJS in dev mode - - runs playwright tests - - send coverage reports to Currents for post-processing - -## Examples - -- Run `npm run test:e2e` for using [`pwc`](https://docs.currents.dev/getting-started/playwright/you-first-playwright-run#using-the-cli) command -- Run `npm run test:e2e:pwc-p` for [orchestrated](https://docs.currents.dev/guides/parallelization-guide/pw-parallelization/playwright-orchestration) runs - -## Licence - -MIT License diff --git a/playwright/code-coverage/instrumented-coverage/source__README.md b/playwright/code-coverage/instrumented-coverage/source__README.md deleted file mode 100644 index 08eb870..0000000 --- a/playwright/code-coverage/instrumented-coverage/source__README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Currents Coverage with Playwright - -Playwright [code coverage](https://docs.currents.dev/guides/coverage) for Currents. - -This is a simple NextJS application. It uses Babel and Instanbul for instrumentating the code, then Playwright runs a set of e2e tests and send the results to Currents for post-processing. - -![currents-2024-11-21-16 21 20@2x](https://github.com/user-attachments/assets/2e2fb1da-31fa-43a7-b84e-670ce1b88c09) - -## Setup - -- Install dependencies with `npm install` -- Update `playwright.config.ts` with Currents [record key](https://docs.currents.dev/guides/record-key) and [project id](https://docs.currents.dev/dashboard/projects/project-settings) -- Run `npm run test` for running tests, behind the scenes: - - - starts NextJS in dev mode - - runs playwright tests - - send coverage reports to Currents for post-processing - -## Examples - -- Run `npm run test:e2e` for using [`pwc`](https://docs.currents.dev/getting-started/playwright/you-first-playwright-run#using-the-cli) command -- Run `npm run test:e2e:pwc-p` for [orchestrated](https://docs.currents.dev/guides/parallelization-guide/pw-parallelization/playwright-orchestration) runs - -## Licence - -MIT License diff --git a/playwright/component-testing/README.md b/playwright/component-testing/README.md index 40a0258..c88eeb2 100644 --- a/playwright/component-testing/README.md +++ b/playwright/component-testing/README.md @@ -1,67 +1,44 @@ -# Playwright Component Testing - -- **Framework:** `playwright` -- **Use case:** `features/component-testing` -- **Source repository:** https://github.com/currents-dev/currents-playwright-component-tests-example - -## What this example does - -A minimal example showing **Playwright Component Testing (React)** reported to **Currents** (using the `pwc` command / Currents Playwright integration). It explicitly notes that Playwright component testing support was **experimental (Nov 2023)**. - -## How this example is used - -1. **Install** - - `npm i` -2. **Create Currents project** - - Create a project in Currents and obtain `projectId` + `recordKey`. -3. **Run via `pwc`** - - Example command: `npx pwc --key --project-id --ci-build-id hello-currents` -4. **Run component tests locally** - - `npm run test-ct` runs `playwright test -c playwright-ct.config.js`. -5. **Artifacts enabled** - - The CT config enables `trace: "on"`, `video: "on"`, `screenshot: "on"` and sets `ctPort: 3100`. - -## What scenarios are included - -- **Two simple component tests** - - `src/App.spec.jsx` (passes, expects “Learn React”). - - `src/AppFailing.spec.jsx` (intentionally fails, expects “Dont Learn React”). -- **A minimal React app scaffold (Create React App)** - - `src/App.js` renders the “Learn React” link/text. -- **Playwright Component Testing configuration** - - `playwright-ct.config.js` demonstrates CT setup + artifact capture. -- **Currents integration dependency** - - Uses `@currents/playwright` in `package.json`. - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Make the README readable in raw form** - - It’s effectively one long line in the raw file, which makes it harder to scan/copy. Reformat into sections + fenced code blocks. -2. **Provide a copy/paste “Quickstart” with env vars** - - Add `.env.example` and show both styles: - - `npx pwc --key ... --project-id ...` - - and/or `CURRENTS_RECORD_KEY=... CURRENTS_PROJECT_ID=... npx pwc ...` (whatever the tool supports) so people don’t paste secrets into shell history. -3. **Clarify what `pwc` is** - - Add one sentence: “`pwc` is the Currents Playwright CLI wrapper that records results to Currents,” plus a link to the official docs (the README already links docs, but doesn’t define `pwc`). -4. **Add a CI snippet** - - Even a tiny GitHub Actions example (Node install + `npm run test-ct` + `npx pwc ...`) would reduce guesswork for real usage. -5. **Pin/upgrade versions or add a compatibility note** - - Since CT was experimental in Nov 2023, add a note about the Playwright CT version expected (repo uses `@playwright/experimental-ct-react` `^1.39.0`). - -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **22** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +# Playwright Component testing with Currents + +Run [Playwright Component testing](https://playwright.dev/docs/test-components) and report the results to [Currents](https://currents.dev/playwright) + +> **Note November 2023:** Playwright support for Component testing is still experimental + +The project contains simple component tests: + +- `src/App.spec.jsx` - a passing test +- `src/AppFailing.spec.jsx` - a failing test + +## Setup + +- First run `npm i` +- Create an account and project at https://app.currents.dev +- Grab the following details: + - `projectId` + - `recordKey` + +## Run + +Run `pwc` command: + +`npx pwc --key --project-id --ci-build-id hello-currents` + +- Explore `playwright-ct.config.js` and note that screenshots, videos and trace are activated +- Explore more about [CI Build Id](https://currents.dev/readme/guides/cypress-ci-build-id) + +Running the command would produce an output that is similar to this: + +![currents-2023-11-02-15 32 59@2x](https://github.com/currents-dev/currents-playwright-component-tests-example/assets/1637928/d270a5f0-2fb0-41e0-b2b0-667db7d6ee7e) + +The results will be reported to Currents Dashboard: + +![demo-currents-pw-ct](https://github.com/currents-dev/currents-playwright-component-tests-example/assets/1637928/a7b95888-416d-407e-bf00-833f893765a7) + +## Explore `@currents/playwright` integration options + +Follow our documentation to explore integration options: +https://currents.dev/readme/integration-with-playwright/currents-playwright + +- Applying tags for better tests managing +- Create additional projects +- Explore diff --git a/playwright/component-testing/README.upstream.md b/playwright/component-testing/README.upstream.md deleted file mode 100644 index c88eeb2..0000000 --- a/playwright/component-testing/README.upstream.md +++ /dev/null @@ -1,44 +0,0 @@ -# Playwright Component testing with Currents - -Run [Playwright Component testing](https://playwright.dev/docs/test-components) and report the results to [Currents](https://currents.dev/playwright) - -> **Note November 2023:** Playwright support for Component testing is still experimental - -The project contains simple component tests: - -- `src/App.spec.jsx` - a passing test -- `src/AppFailing.spec.jsx` - a failing test - -## Setup - -- First run `npm i` -- Create an account and project at https://app.currents.dev -- Grab the following details: - - `projectId` - - `recordKey` - -## Run - -Run `pwc` command: - -`npx pwc --key --project-id --ci-build-id hello-currents` - -- Explore `playwright-ct.config.js` and note that screenshots, videos and trace are activated -- Explore more about [CI Build Id](https://currents.dev/readme/guides/cypress-ci-build-id) - -Running the command would produce an output that is similar to this: - -![currents-2023-11-02-15 32 59@2x](https://github.com/currents-dev/currents-playwright-component-tests-example/assets/1637928/d270a5f0-2fb0-41e0-b2b0-667db7d6ee7e) - -The results will be reported to Currents Dashboard: - -![demo-currents-pw-ct](https://github.com/currents-dev/currents-playwright-component-tests-example/assets/1637928/a7b95888-416d-407e-bf00-833f893765a7) - -## Explore `@currents/playwright` integration options - -Follow our documentation to explore integration options: -https://currents.dev/readme/integration-with-playwright/currents-playwright - -- Applying tags for better tests managing -- Create additional projects -- Explore diff --git a/playwright/component-testing/source__README.md b/playwright/component-testing/source__README.md deleted file mode 100644 index c88eeb2..0000000 --- a/playwright/component-testing/source__README.md +++ /dev/null @@ -1,44 +0,0 @@ -# Playwright Component testing with Currents - -Run [Playwright Component testing](https://playwright.dev/docs/test-components) and report the results to [Currents](https://currents.dev/playwright) - -> **Note November 2023:** Playwright support for Component testing is still experimental - -The project contains simple component tests: - -- `src/App.spec.jsx` - a passing test -- `src/AppFailing.spec.jsx` - a failing test - -## Setup - -- First run `npm i` -- Create an account and project at https://app.currents.dev -- Grab the following details: - - `projectId` - - `recordKey` - -## Run - -Run `pwc` command: - -`npx pwc --key --project-id --ci-build-id hello-currents` - -- Explore `playwright-ct.config.js` and note that screenshots, videos and trace are activated -- Explore more about [CI Build Id](https://currents.dev/readme/guides/cypress-ci-build-id) - -Running the command would produce an output that is similar to this: - -![currents-2023-11-02-15 32 59@2x](https://github.com/currents-dev/currents-playwright-component-tests-example/assets/1637928/d270a5f0-2fb0-41e0-b2b0-667db7d6ee7e) - -The results will be reported to Currents Dashboard: - -![demo-currents-pw-ct](https://github.com/currents-dev/currents-playwright-component-tests-example/assets/1637928/a7b95888-416d-407e-bf00-833f893765a7) - -## Explore `@currents/playwright` integration options - -Follow our documentation to explore integration options: -https://currents.dev/readme/integration-with-playwright/currents-playwright - -- Applying tags for better tests managing -- Create additional projects -- Explore diff --git a/playwright/orchestration/README.md b/playwright/orchestration/README.md index 8a609ad..f63b773 100644 --- a/playwright/orchestration/README.md +++ b/playwright/orchestration/README.md @@ -1,70 +1,33 @@ -# Playwright Orchestration +# Currents Orchestration Example -- **Framework:** `playwright` -- **Use case:** `features/orchestration` -- **Source repository:** https://github.com/currents-dev/currents-playwright-orchestration-example +[Demo video](https://www.loom.com/share/e2a4ec0167d74e69b9f07d45707cf0f4?sid=b003d756-0e5d-400d-b2a8-3279b63804f2) -## What this example does +### Configuring Batch Size -An example repo that demonstrates how **Currents Orchestration** (batched orchestration) can reduce Playwright CI time versus **native Playwright sharding**, using a synthetic suite with mixed test durations and reporting the benchmark numbers in the README. +It is recommended to set `batchSize = workers` -## How this example is used +- Use `--pwc-batch-size` CLI params, e.g.: `pwc-p --pwc-batch-size=3` +- Set environment variable `CURRENTS_BATCH_SIZE` e.g.: `CURRENTS_BATCH_SIZE=3` +- Set the values in `currents.confg.ts`, e.g.: `orchestration.batchSize: 3` -- Configure Currents with environment variables: - - `CURRENTS_RECORD_KEY` - - `CURRENTS_PROJECT_ID` - - Optional orchestration batch size via `CURRENTS_BATCH_SIZE` (or CLI `--pwc-batch-size`, or config file). -- Run Playwright with **native sharding** (baseline) using the Playwright config (`workers: 2`, tests under `./tests`). -- Run using **Currents Orchestration** with a chosen batch size (README recommends `batchSize = workers`; config defaults to `batchSize: 2`). - (Orchestration conceptually pulls/dispatches tests dynamically; Currents docs recommend using blob reporter + merging when runs are fragmented.) +### Suite Composition -## What scenarios are included +- 40 long-running tests: 110-120s +- 40 short tests: 10-30s -- **Benchmark comparison (documented in README):** - - Native sharding: workers=2, machines=5, duration **15m 38s** - - Batched orchestration: batch size=2, workers=2, machines=5, duration **9m 17s** (~41% faster) -- **Currents config example** with orchestration settings: - - `currents.config.ts` shows `orchestration.batchSize: 2` and reads keys from env. -- **Playwright config example:** - - `playwright.config.ts` sets `timeout`, `workers: 2`, `testDir: ./tests`, outputDir `test-results/`. -- **Synthetic suite generator scripts:** - - `generate-tests.mjs` generates **100** specs with randomized durations (20 long, 30 mid, 50 short) into `./tests`. - - `generate-tests-edge-case.mjs` generates an “edge case” suite into `./edge-case-tests` (40 long + 40 short). -- **Dependencies** pinned to demonstrate the setup: - - `@currents/playwright` and `@playwright/test` are included. +### Playwright Sharding -## How to implement this in your own project +- workers: 2 +- machines: 5 +- overall duration: **15m 38s** 🐌 -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. +![currents-2025-04-28-16 38 18@2x](https://github.com/user-attachments/assets/2ab6b34a-634d-46a3-810b-bbfa4487cd20) -### Implementation notes from the audit +### Currents Batched Orchestration -1. **Add a real Quickstart section** - - Right now README is only benchmarks + batch size notes; add exact commands for: - - generating tests - - native sharding run - - orchestration run (include `pwc-p` command, `CURRENTS_CI_BUILD_ID`, etc.). -2. **Add `npm` scripts** - - `package.json` has only the placeholder `test` script; add `gen`, `run:shard`, `run:or8n` scripts so users can copy/paste. -3. **Fix small correctness issues** - - README references `currents.confg.ts` (typo) and Playwright project name is `"chromim"` (typo). -4. **Show the CI workflow(s) explicitly** - - There’s a `.github/workflows` folder, but README doesn’t list files or explain how “machines=5” is achieved; include a minimal GitHub Actions matrix example in README. -5. **Reformat files** - - README/configs/scripts are committed as single-line files, which makes learning/copying harder—format them normally. -6. **Explain orchestration reporting implications** - - Add a short note: orchestration may run multiple Playwright processes per machine, so recommend blob + merge (with links) and show the exact config snippet. +- batch size: 2 +- workers: 2 +- machines: 5 +- overall duration: **9m 17s** (~41% improvement) 🏎️ -## Source markdown copied into this folder - -- [`source__README.md`](source__README.md) - -## Repository content copied into this folder - -- Total tracked files copied: **90** -- Source `README.md` is saved as `README.upstream.md`. -- Path mapping: [`content-map.md`](content-map.md) +![currents-2025-04-28-16 39 34@2x](https://github.com/user-attachments/assets/206a87f1-3f1d-4bcd-bb96-88855acd455d) diff --git a/playwright/orchestration/README.upstream.md b/playwright/orchestration/README.upstream.md deleted file mode 100644 index f63b773..0000000 --- a/playwright/orchestration/README.upstream.md +++ /dev/null @@ -1,33 +0,0 @@ -# Currents Orchestration Example - -[Demo video](https://www.loom.com/share/e2a4ec0167d74e69b9f07d45707cf0f4?sid=b003d756-0e5d-400d-b2a8-3279b63804f2) - -### Configuring Batch Size - -It is recommended to set `batchSize = workers` - -- Use `--pwc-batch-size` CLI params, e.g.: `pwc-p --pwc-batch-size=3` -- Set environment variable `CURRENTS_BATCH_SIZE` e.g.: `CURRENTS_BATCH_SIZE=3` -- Set the values in `currents.confg.ts`, e.g.: `orchestration.batchSize: 3` - -### Suite Composition - -- 40 long-running tests: 110-120s -- 40 short tests: 10-30s - -### Playwright Sharding - -- workers: 2 -- machines: 5 -- overall duration: **15m 38s** 🐌 - -![currents-2025-04-28-16 38 18@2x](https://github.com/user-attachments/assets/2ab6b34a-634d-46a3-810b-bbfa4487cd20) - -### Currents Batched Orchestration - -- batch size: 2 -- workers: 2 -- machines: 5 -- overall duration: **9m 17s** (~41% improvement) 🏎️ - -![currents-2025-04-28-16 39 34@2x](https://github.com/user-attachments/assets/206a87f1-3f1d-4bcd-bb96-88855acd455d) diff --git a/playwright/orchestration/source__README.md b/playwright/orchestration/source__README.md deleted file mode 100644 index f63b773..0000000 --- a/playwright/orchestration/source__README.md +++ /dev/null @@ -1,33 +0,0 @@ -# Currents Orchestration Example - -[Demo video](https://www.loom.com/share/e2a4ec0167d74e69b9f07d45707cf0f4?sid=b003d756-0e5d-400d-b2a8-3279b63804f2) - -### Configuring Batch Size - -It is recommended to set `batchSize = workers` - -- Use `--pwc-batch-size` CLI params, e.g.: `pwc-p --pwc-batch-size=3` -- Set environment variable `CURRENTS_BATCH_SIZE` e.g.: `CURRENTS_BATCH_SIZE=3` -- Set the values in `currents.confg.ts`, e.g.: `orchestration.batchSize: 3` - -### Suite Composition - -- 40 long-running tests: 110-120s -- 40 short tests: 10-30s - -### Playwright Sharding - -- workers: 2 -- machines: 5 -- overall duration: **15m 38s** 🐌 - -![currents-2025-04-28-16 38 18@2x](https://github.com/user-attachments/assets/2ab6b34a-634d-46a3-810b-bbfa4487cd20) - -### Currents Batched Orchestration - -- batch size: 2 -- workers: 2 -- machines: 5 -- overall duration: **9m 17s** (~41% improvement) 🏎️ - -![currents-2025-04-28-16 39 34@2x](https://github.com/user-attachments/assets/206a87f1-3f1d-4bcd-bb96-88855acd455d) diff --git a/playwright/pnpm/README.md b/playwright/pnpm/README.md index 377b0f7..acb7537 100644 --- a/playwright/pnpm/README.md +++ b/playwright/pnpm/README.md @@ -1,70 +1,30 @@ -# Playwright with pnpm +# currents-playwright-pnpm-example -- **Framework:** `playwright` -- **Use case:** `workspace/pnpm` -- **Source repository:** Consolidated from `currents-playwright-pnpm-example` and `currents-pnpm` - -## What this example does - -This example demonstrates how to use **Currents** with **Playwright** in a **pnpm** workspace. It includes two sets of tests: -1. **Basic Tests** (`tests/basic/`): Standard Playwright tests demonstrating basic usage and visual diffs (some tests are designed to fail for demonstration). -2. **Chromatic Integration** (`tests/chromatic/`): Tests demonstrating integration with **Chromatic** for visual testing alongside Currents. - -## Key Features - -- **Currents Orchestration**: Uses `pwc-p` for orchestrating tests. -- **GitHub Actions Integration**: Includes a workflow `.github/workflows/integration.yml` for CI execution. -- **Visual Testing**: - - Standard Playwright visual snapshots (in `tests/basic`). - - Chromatic visual testing (in `tests/chromatic`). -- **Artifacts**: Configured to upload artifacts (screenshots, videos, traces). - -## Usage +An example repository for setting up Currents + Chromatic and run Playwright tests on GitHub Actions ### Setup -```bash -pnpm install -``` - -### Run Tests Locally -**Run all tests:** -```bash -pnpm test +```sh +pnpm install ``` -**Run basic tests only:** -```bash -pnpm run test:basic -``` +### Run tests locally -**Run Chromatic tests only:** -```bash -pnpm run test:chromatic -``` +Set your own `CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID`: -**Run with Currents Orchestration:** -```bash -export CURRENTS_RECORD_KEY= -export CURRENTS_PROJECT_ID= -pnpm run pwc-p +```sh +CURRENTS_RECORD_KEY=xxx CURRENTS_PROJECT_ID=yyy pnpm exec pwc-p ``` -### GitHub Actions - -The included workflow `.github/workflows/integration.yml` demonstrates: -- Installing dependencies with pnpm. -- Running tests with `pwc-p` and the blob reporter. -- Merging blob reports into an HTML report. -- Uploading artifacts. -- Running Chromatic visual tests in a separate job. +GitHub Actions: -## Configuration +- Set `CURRENTS_RECORD_KEY` and `CHROMATIC_PROJECT_TOKEN` [repository secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) +- Set Currents project id in `currents.config.ts:config.projectId` in `currents.config.ts` -- **playwright.config.ts**: Configured to look for tests in the `tests/` directory. -- **currents.config.ts**: Configures Currents project ID and record key from environment variables. +Check out a GitHub Actions [example build](https://github.com/currents-dev/currents-playwright-pnpm-example/actions/runs/13893721273). -## Notes +### Configuration Notes -- The `tests/basic` directory contains tests that may fail intentionally (e.g., `failing test`) to demonstrate reporting capabilities. -- The `tests/chromatic` directory requires Chromatic configuration if you want to use the visual testing features fully. +- [Currents Reporter](https://docs.currents.dev/resources/reporters/currents-playwright) is configured in playwright.config.ts +- pwc-p runs Playwright using [Currents Orchestration](https://docs.currents.dev/guides/parallelization-guide/pw-parallelization/playwright-orchestration) +- Chromatic collects the visual testing artifacts as a [separate GHA job](https://github.com/currents-dev/currents-playwright-pnpm-example/blob/60499037a5674ea3fd6082e9664fb9968cc442f4/.github/workflows/integration.yml#L73) diff --git a/playwright/pnpm/README.upstream.md b/playwright/pnpm/README.upstream.md deleted file mode 100644 index acb7537..0000000 --- a/playwright/pnpm/README.upstream.md +++ /dev/null @@ -1,30 +0,0 @@ -# currents-playwright-pnpm-example - -An example repository for setting up Currents + Chromatic and run Playwright tests on GitHub Actions - -### Setup - -```sh -pnpm install -``` - -### Run tests locally - -Set your own `CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID`: - -```sh -CURRENTS_RECORD_KEY=xxx CURRENTS_PROJECT_ID=yyy pnpm exec pwc-p -``` - -GitHub Actions: - -- Set `CURRENTS_RECORD_KEY` and `CHROMATIC_PROJECT_TOKEN` [repository secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) -- Set Currents project id in `currents.config.ts:config.projectId` in `currents.config.ts` - -Check out a GitHub Actions [example build](https://github.com/currents-dev/currents-playwright-pnpm-example/actions/runs/13893721273). - -### Configuration Notes - -- [Currents Reporter](https://docs.currents.dev/resources/reporters/currents-playwright) is configured in playwright.config.ts -- pwc-p runs Playwright using [Currents Orchestration](https://docs.currents.dev/guides/parallelization-guide/pw-parallelization/playwright-orchestration) -- Chromatic collects the visual testing artifacts as a [separate GHA job](https://github.com/currents-dev/currents-playwright-pnpm-example/blob/60499037a5674ea3fd6082e9664fb9968cc442f4/.github/workflows/integration.yml#L73) diff --git a/playwright/pnpm/source__README.md b/playwright/pnpm/source__README.md deleted file mode 100644 index acb7537..0000000 --- a/playwright/pnpm/source__README.md +++ /dev/null @@ -1,30 +0,0 @@ -# currents-playwright-pnpm-example - -An example repository for setting up Currents + Chromatic and run Playwright tests on GitHub Actions - -### Setup - -```sh -pnpm install -``` - -### Run tests locally - -Set your own `CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID`: - -```sh -CURRENTS_RECORD_KEY=xxx CURRENTS_PROJECT_ID=yyy pnpm exec pwc-p -``` - -GitHub Actions: - -- Set `CURRENTS_RECORD_KEY` and `CHROMATIC_PROJECT_TOKEN` [repository secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) -- Set Currents project id in `currents.config.ts:config.projectId` in `currents.config.ts` - -Check out a GitHub Actions [example build](https://github.com/currents-dev/currents-playwright-pnpm-example/actions/runs/13893721273). - -### Configuration Notes - -- [Currents Reporter](https://docs.currents.dev/resources/reporters/currents-playwright) is configured in playwright.config.ts -- pwc-p runs Playwright using [Currents Orchestration](https://docs.currents.dev/guides/parallelization-guide/pw-parallelization/playwright-orchestration) -- Chromatic collects the visual testing artifacts as a [separate GHA job](https://github.com/currents-dev/currents-playwright-pnpm-example/blob/60499037a5674ea3fd6082e9664fb9968cc442f4/.github/workflows/integration.yml#L73)