feat: process SPEC environment variable (#2)

* feat: process SPEC environment variable

* add readme block

.github/workflows/ci.yml

@@ -20,6 +20,25 @@ jobs:
       - name: Print result 🖨
         run: echo '${{ steps.prepare.outputs.matrix }}'
 
+  # two jobs that split 2 explicit specs
+  test-spec:
+    runs-on: ubuntu-20.04
+    strategy:
+      fail-fast: false
+      matrix:
+        containers: [1, 2]
+    steps:
+      - name: Checkout 🛎
+        uses: actions/checkout@v3
+      - name: Run split Cypress tests 🧪
+        # https://github.com/cypress-io/github-action
+        uses: cypress-io/github-action@v5
+        # using operating system process environment variables
+        env:
+          SPEC: 'cypress/e2e/spec-b.cy.js,cypress/e2e/spec-e.cy.js'
+          SPLIT: ${{ strategy.job-total }}
+          SPLIT_INDEX: ${{ strategy.job-index }}
+
   test-split:
     needs: prepare
     runs-on: ubuntu-20.04
@@ -39,13 +58,14 @@ jobs:
       - name: Run split Cypress tests 🧪
         # https://github.com/cypress-io/github-action
         uses: cypress-io/github-action@v5
+        # using operating system process environment variables
         env:
           SPLIT: ${{ strategy.job-total }}
           SPLIT_INDEX: ${{ strategy.job-index }}
 
   release:
     if: github.ref == 'refs/heads/main'
-    needs: test-split
+    needs: [test-split, test-spec]
     runs-on: ubuntu-20.04
     steps:
       - name: Checkout 🛎

README.md

@@ -126,6 +126,29 @@ setupNodeEvents(on, config) {
 }
 ```
 
+## List of specs
+
+Suppose you want to run some specs first, for example [just the changed specs](https://glebbahmutov.com/blog/trace-changed-specs/). You would compute the list of specs and then call Cypress `run` command with the `--spec` parameter
+
+```
+$ npx cypress run --spec "spec1,spec2,spec3"
+```
+
+You can still split the specs across several machines using `cypress-split`, just move the `--spec` list (or duplicate it) to a process or Cypress env variable `spec`:
+
+```
+# using process environment variables split all specs across 2 machines
+$ SPEC="spec1,spec2,spec3",SPLIT=2,SPLIT_INDEX=0 npx cypress run --spec "spec1,spec2,spec3"
+$ SPEC="spec1,spec2,spec3",SPLIT=2,SPLIT_INDEX=1 npx cypress run --spec "spec1,spec2,spec3"
+
+# using Cypress "env" option
+$ npx cypress run --env split=2,splitIndex=0,spec="spec1,spec2,spec3"
+$ npx cypress run --env split=2,splitIndex=1,spec="spec1,spec2,spec3"
+
+# for CIs with automatically index detection
+$ npx cypress run --env split=true,spec="spec1,spec2,spec3"
+```
+
 ## Debugging
 
 To see diagnostic log messages from this plugin, set the environment variable `DEBUG=cypress-split`

src/index.js

@@ -36,9 +36,9 @@ function cypressSplit(on, config) {
     config = on
   }
 
-  if (config.specs) {
+  if (config.spec) {
     debug('config has specs set')
-    debug(config.specs)
+    debug(config.spec)
   }
 
   // the user can specify the split flag / numbers
@@ -49,6 +49,21 @@ function cypressSplit(on, config) {
 
   let SPLIT = process.env.SPLIT || config.env.split || config.env.SPLIT
   let SPLIT_INDEX = process.env.SPLIT_INDEX || config.env.splitIndex
+  // potentially a list of files to run / split
+  let SPEC = process.env.SPEC || config.env.spec || config.env.SPEC
+  let specs
+  if (typeof SPEC === 'string' && SPEC) {
+    specs = SPEC.split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+    console.log(
+      '%s have explicit %d spec %s',
+      label,
+      specs.length,
+      specs.length === 1 ? 'file' : 'files',
+    )
+  }
+
   if (SPLIT === 'true' || SPLIT === true) {
     // the user wants us to determine the machine index
     // and the total number of machines, which is possible for some CI systems
@@ -80,7 +95,10 @@ function cypressSplit(on, config) {
   }
 
   if (isDefined(SPLIT) && isDefined(SPLIT_INDEX)) {
-    const specs = getSpecs(config)
+    if (!specs) {
+      specs = getSpecs(config)
+    }
+
     console.log('%s there are %d found specs', label, specs.length)
     // console.log(specs)
     const splitN = Number(SPLIT)