feat: adding preview command (#196)

* feat: adding preview command

* update the variable name

* move specs

* move CI detection

* more work

* remove comments

* move finding specs

* getting specs

* move the code

* demo preview

* add to README

* chunk index

.github/workflows/ci.yml

@@ -84,6 +84,26 @@ jobs:
           echo off
           echo '${{ steps.merge.outputs.merged }}'
 
+  preview:
+    needs: prepare
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout 🛎
+        uses: actions/checkout@v4
+
+      - name: Preview the split 🧪
+        # https://github.com/cypress-io/github-action
+        uses: cypress-io/github-action@v5
+        with:
+          command: npm run demo-preview
+
+      - name: Preview the split with timings 🧪
+        # https://github.com/cypress-io/github-action
+        uses: cypress-io/github-action@v5
+        with:
+          install: false
+          command: npm run demo-preview -- --split-file ./timings.json
+
   test-split:
     needs: prepare
     runs-on: ubuntu-22.04
@@ -251,6 +271,7 @@ jobs:
         test-timings-no-file,
         test-merge-timings,
         test-find-timings-file,
+        preview,
       ]
     runs-on: ubuntu-22.04
     steps:

README.md

@@ -285,6 +285,17 @@ See example [bahmutov/cypress-split-timings-example](https://github.com/bahmutov
 
 **Note 2:** during Cypress execution, the working directory is set to the folder with the Cypress config file. This module tries its best to find the split file by searching the parent folders to the Git repo or root folder.
 
+## Preview
+
+You can see how this plugin is going to split the specs using the `cypress-split-preview` alias
+
+```
+# show the split across N machines
+$ npx cypress-split-preview --split <N>
+# show the split across N machines based on spec timings
+$ npx cypress-split-preview --split <N> --split-file <JSON filename>
+```
+
 ## Merging timings files
 
 This module includes a bin utility to merge multiple timings files into one. Example:

bin/preview.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+// @ts-check
+
+const arg = require('arg')
+const debug = require('debug')('cypress-split')
+const label = 'cypress-split-preview'
+const { version } = require('../package.json')
+const { getSpecsToSplit } = require('../src/parse-inputs')
+const { splitSpecsLogic } = require('../src/utils')
+
+console.log('%s Version %s', label, version)
+
+const args = arg({
+  '--split': Number,
+  '--split-file': String,
+})
+debug(args)
+
+const n = args['--split']
+console.log('%s split %d ways', label, n)
+const specs = getSpecsToSplit(process.env)
+console.log('%s found %d specs', label, specs.length)
+debug(specs)
+
+if (typeof n !== 'number') {
+  throw new Error('Please provide --split N')
+}
+
+for (let k = 0; k < n; k += 1) {
+  console.log('%s chunk %d of %d', label, k + 1, n)
+  splitSpecsLogic({
+    specs,
+    splitN: n,
+    splitIndex: k,
+    splitFileName: args['--split-file'],
+    label,
+  })
+}

package.json

@@ -4,7 +4,8 @@
   "description": "Split Cypress specs across parallel CI machines for speed",
   "main": "src/index.js",
   "bin": {
-    "cypress-split-merge": "./bin/merge.js"
+    "cypress-split-merge": "./bin/merge.js",
+    "cypress-split-preview": "./bin/preview.js"
   },
   "files": [
     "src",
@@ -25,7 +26,8 @@
     "timings": "DEBUG=cypress-split SPLIT=2 SPLIT_INDEX=0 SPLIT_FILE=timings.json cypress run",
     "timings-no-file": "DEBUG=cypress-split SPLIT=1 SPLIT_INDEX=0 SPLIT_FILE=does-not-exist.json cypress run",
     "timings-split-output-file": "DEBUG=cypress-split SPLIT=2 SPLIT_INDEX=0 SPLIT_OUTPUT_FILE=new-timings.json SPLIT_FILE=timings.json cypress run",
-    "demo-merge": "node ./bin/merge --parent-folder examples/split-times --split-file timings.json --output out-timings.json"
+    "demo-merge": "node ./bin/merge --parent-folder examples/split-times --split-file timings.json --output out-timings.json",
+    "demo-preview": "node ./bin/preview --split 2"
   },
   "repository": {
     "type": "git",