wait for event loop to drain (#1002)

Author: charlierudolph

CHANGELOG.md

@@ -2,6 +2,10 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO
 
 ### [Unreleased](https://github.com/cucumber/cucumber-js/compare/v3.2.1...master) (In Git)
 
+#### BREAKING CHANGES
+
+* cucumber now waits for the event loop to drain before exiting. To exit immediately when the tests finish running use `--exit`. Use of this flag is discouraged. See [here](/docs/cli.md#exiting) for more information
+
 ### [3.2.1](https://github.com/cucumber/cucumber-js/compare/v3.2.0...v3.2.1) (2017-01-03)
 
 #### Bug Fixes

docs/cli.md

@@ -70,6 +70,14 @@ You can pass in format options with `--format-options <JSON>`. The JSON string m
 
 Colors can be disabled with `--format-options '{"colorsEnabled": false}'`
 
+## Exiting
+
+By default, cucumber exits when the event loop drains. Use the `--exit` flag in order to force shutdown of the event loop when the test run has finished. This is discouraged, as fixing the issues that causes the hang is a better long term solution. Some potential resources for that are:
+* [Node.js guide to debugging](https://nodejs.org/en/docs/inspector/)
+* NPM package [why-is-node-running](https://www.npmjs.com/package/why-is-node-running)
+* [Node.js Async Hooks](https://nodejs.org/dist/latest-v8.x/docs/api/async_hooks.html)
+* Isolating what scenario or scenarios causes the hang
+
 ## Undefined Step Snippets
 
 Undefined steps snippets are printed in javascript using the callback interface by default.

features/exit.feature

@@ -0,0 +1,41 @@
+@spawn
+Feature: Exit
+
+  Use `--exit` to exit when the test run finishes without
+  waiting to the even loop to drain
+
+  Background:
+    Given a file named "features/a.feature" with:
+      """
+      Feature:
+        Scenario:
+          Given a step
+      """
+    Given a file named "features/step_definitions/cucumber_steps.js" with:
+      """
+      import {defineSupportCode, After} from 'cucumber'
+
+      defineSupportCode(({Given}) => {
+        Given('a step', function() {})
+      })
+
+      After(() => {
+        setTimeout(() => {
+          console.log('external process done')
+        }, 1000)
+      })
+      """
+
+  Scenario: by default wait for the event loop to drain
+    When I run cucumber.js
+    Then the output contains the text:
+      """
+      external process done
+      """
+
+  Scenario: exit immediately without waiting for the even loop to drain
+    When I run cucumber.js with `--exit`
+    Then the output does not contain the text:
+      """
+      external process done
+      """

features/step_definitions/cli_steps.js

@@ -47,6 +47,12 @@ defineSupportCode(function({ When, Then }) {
     expect(actualOutput).to.include(expectedOutput)
   })
 
+  Then('the output does not contain the text:', function(text) {
+    const actualOutput = normalizeText(this.lastRun.output)
+    const expectedOutput = normalizeText(text)
+    expect(actualOutput).not.to.include(expectedOutput)
+  })
+
   Then(/^the error output contains the text snippets:$/, function(table) {
     const actualOutput = normalizeText(this.lastRun.errorOutput)
     table.rows().forEach(row => {

features/support/world.js

@@ -38,7 +38,8 @@ class World {
       })
       let error, stderr
       try {
-        if (!await cli.run()) {
+        const { success } = await cli.run()
+        if (!success) {
           error = new Error('CLI exited with non-zero')
           error.code = 42
         }

src/cli/argv_parser.js

@@ -52,6 +52,10 @@ export default class ArgvParser {
         []
       )
       .option('-d, --dry-run', 'invoke formatters without executing steps')
+      .option(
+        '--exit',
+        'force shutdown of the event loop when the test run has finished: cucumber will call process.exit'
+      )
       .option('--fail-fast', 'abort the run on first failure')
       .option(
         '-f, --format <TYPE[:PATH]>',

src/cli/configuration_builder.js

@@ -58,6 +58,7 @@ export default class ConfigurationBuilder {
         strict: !!this.options.strict,
         worldParameters: this.options.worldParameters
       },
+      shouldExitImmediately: !!this.options.exit,
       supportCodePaths
     }
   }

src/cli/configuration_builder_spec.js

@@ -46,6 +46,7 @@ describe('Configuration', function() {
           strict: true,
           worldParameters: {}
         },
+        shouldExitImmediately: false,
         supportCodePaths: []
       })
     })

src/cli/index.js

@@ -67,11 +67,11 @@ export default class Cli {
     const configuration = await this.getConfiguration()
     if (configuration.listI18nLanguages) {
       this.stdout.write(I18n.getLanguages())
-      return true
+      return { success: true }
     }
     if (configuration.listI18nKeywordsFor) {
       this.stdout.write(I18n.getKeywords(configuration.listI18nKeywordsFor))
-      return true
+      return { success: true }
     }
     const supportCodeLibrary = this.getSupportCodeLibrary(
       configuration.supportCodePaths
@@ -96,8 +96,11 @@ export default class Cli {
       supportCodeLibrary,
       testCases
     })
-    const result = await runtime.start()
+    const success = await runtime.start()
     await cleanup()
-    return result
+    return {
+      shouldExitImmediately: configuration.shouldExitImmediately,
+      success
+    }
   }
 }

src/cli/run.js

@@ -14,22 +14,17 @@ export default async function run() {
     stdout: process.stdout
   })
 
-  let success
+  let result
   try {
-    success = await cli.run()
+    result = await cli.run()
   } catch (error) {
     exitWithError(error)
   }
 
-  const exitCode = success ? 0 : 1
-  function exitNow() {
+  const exitCode = result.success ? 0 : 1
+  if (result.shouldExitImmediately) {
     process.exit(exitCode)
-  }
-
-  // If stdout.write() returned false, kernel buffer is not empty yet
-  if (process.stdout.write('')) {
-    exitNow()
   } else {
-    process.stdout.on('drain', exitNow)
+    process.exitCode = exitCode
   }
 }