[cucumber#1044] Refactoring out nextPickleIndex + README example as test

Author: eman2673

features/parallel_custom_assign.feature

@@ -78,4 +78,57 @@ Feature: Running scenarios in parallel with custom assignment
     And the output contains the text:
     """
       #1 was test 2 on this worker
-    """
+    """
+
+  Scenario: assignment is appropriately applied and fails at last processed scenario 'a'
+    Given a file named "features/step_definitions/cucumber_steps.js" with:
+      """
+      const {Given, setParallelCanAssign} = require('@cucumber/cucumber')
+      const _ = require('lodash')
+      const {expect} = require('chai')
+      let worker = null;
+      let processed = 0;
+      setParallelCanAssign((pickleInQuestion, picklesInProgress) => _.isEmpty(pickleInQuestion.tags)
+        || _.every(picklesInProgress, ({tags}) => _.isEmpty(tags) || tags[0].name !== pickleInQuestion.tags[0].name))
+
+      function step_def(name, delay) {
+        return function(scenario, cb) {
+          if (worker == null) worker = name;
+          expect(worker).to.eq(name)
+          expect(scenario).to.eq(++processed)
+          setTimeout(cb, delay)
+        }
+      }
+
+      Given(/^scenario complex (\d+)$/, step_def('A', 300))
+      Given(/^scenario simple (\d+)$/, step_def('B', 200))
+      """
+    And a file named "features/a.feature" with:
+      """
+      Feature: adheres to setParallelCanAssign handler
+        @complex
+        Scenario: 1
+          Given scenario complex 1
+
+        @complex
+        Scenario: 2
+          Given scenario complex 2
+
+        @complex
+        Scenario: 3
+          Given scenario complex 3
+
+        @simple
+        Scenario: 4
+          Given scenario simple 1
+
+        @simple
+        Scenario: 5
+          Given scenario simple 2
+
+        @simple
+        Scenario: 6
+          Given scenario simple 3
+      """
+    When I run cucumber-js with `--parallel 2`
+    Then it passes

src/runtime/parallel/README.md

@@ -10,7 +10,7 @@ where the first tag doesn't match the first tag of any in progress tests.
 import { setParallelCanAssign } from '@cucumber/cucumber'
 // Accept tests missing tags or no test is running having the same first tag
 setParallelCanAssign((pickleInQuestion, picklesInProgress) => _.isEmpty(pickleInQuestion.tags) 
-    || _.every(picklesInProgress, ({tags}) => _.isEmpty(tags) || tags[0].name !== picklesInProgress.tags[0].name))
+    || _.every(picklesInProgress, ({tags}) => _.isEmpty(tags) || tags[0].name !== pickleInQuestion.tags[0].name))
 ```
 * Example using the handler above
 * 2 workers, `A` and `B`

src/runtime/parallel/coordinator.ts

@@ -57,7 +57,6 @@ export default class Coordinator {
   private readonly eventDataCollector: EventDataCollector
   private readonly stopwatch: ITestRunStopwatch
   private onFinish: (success: boolean) => void
-  private nextPickleIdIndex: number
   private readonly options: IRuntimeOptions
   private readonly pickleIds: string[]
   private inProgressPickles: Dictionary<messages.IPickle>
@@ -90,7 +89,6 @@ export default class Coordinator {
     this.supportCodePaths = supportCodePaths
     this.supportCodeRequiredModules = supportCodeRequiredModules
     this.pickleIds = pickleIds
-    this.nextPickleIdIndex = 0
     this.success = true
     this.workers = {}
     this.inProgressPickles = {}
@@ -169,10 +167,7 @@ export default class Coordinator {
       return worker.state !== WorkerState.idle
     })
 
-    if (
-      _.isEmpty(this.inProgressPickles) &&
-      this.pickleIds.length > this.nextPickleIdIndex
-    ) {
+    if (_.isEmpty(this.inProgressPickles) && this.pickleIds.length > 0) {
       this.giveWork(workers[0], true)
       this.idleInterventions++
     }
@@ -262,54 +257,47 @@ export default class Coordinator {
   }
 
   nextPicklePlacement(): IPicklePlacement {
-    for (
-      let index = this.nextPickleIdIndex;
-      index < this.pickleIds.length;
-      index++
-    ) {
-      const pickle = this.eventDataCollector.getPickle(this.pickleIds[index])
+    for (let index = 0; index < this.pickleIds.length; index++) {
+      const placement = this.placementAt(index)
       if (
         this.supportCodeLibrary.parallelCanAssign(
-          pickle,
+          placement.pickle,
           _.values(this.inProgressPickles)
         )
       ) {
-        return { index, pickle }
+        return placement
       }
     }
 
     return null
   }
 
+  placementAt(index: number): IPicklePlacement {
+    return {
+      index,
+      pickle: this.eventDataCollector.getPickle(this.pickleIds[index]),
+    }
+  }
+
   giveWork(worker: IWorker, force: boolean = false): void {
-    if (this.nextPickleIdIndex >= this.pickleIds.length) {
+    if (this.pickleIds.length < 1) {
       const finalizeCommand: IWorkerCommand = { finalize: true }
       worker.state = WorkerState.running
       worker.process.send(finalizeCommand)
       return
     }
 
     const picklePlacement = force
-      ? {
-          index: this.nextPickleIdIndex,
-          pickle: this.eventDataCollector.getPickle(
-            this.pickleIds[this.nextPickleIdIndex]
-          ),
-        }
+      ? this.placementAt(0)
       : this.nextPicklePlacement()
+
     if (picklePlacement === null) {
       return
     }
 
-    if (this.nextPickleIdIndex !== picklePlacement.index) {
-      this.pickleIds.splice(
-        picklePlacement.index,
-        0,
-        this.pickleIds.splice(this.nextPickleIdIndex, 1)[0]
-      )
-    }
-    this.nextPickleIdIndex += 1
-    const pickle = picklePlacement.pickle
+    const { index: nextPickleIndex, pickle } = picklePlacement
+
+    this.pickleIds.splice(nextPickleIndex, 1)
     this.inProgressPickles[worker.id] = pickle
     const gherkinDocument = this.eventDataCollector.getGherkinDocument(
       pickle.uri