{"id":20000430,"url":"https://github.com/knpwrs/gulp-spawn-mocha","last_synced_at":"2025-05-04T15:32:24.954Z","repository":{"id":13732885,"uuid":"16427196","full_name":"knpwrs/gulp-spawn-mocha","owner":"knpwrs","description":"Runs Mocha as a child process in Gulp.","archived":false,"fork":false,"pushed_at":"2024-04-18T17:24:31.000Z","size":288,"stargazers_count":87,"open_issues_count":7,"forks_count":20,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-06T18:52:55.115Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knpwrs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-02-01T02:54:27.000Z","updated_at":"2023-04-29T09:15:25.000Z","dependencies_parsed_at":"2024-06-18T13:38:38.920Z","dependency_job_id":"6f5c8e1c-a4a0-4676-a997-27d57303aa1d","html_url":"https://github.com/knpwrs/gulp-spawn-mocha","commit_stats":{"total_commits":125,"total_committers":18,"mean_commits":6.944444444444445,"dds":"0.33599999999999997","last_synced_commit":"8ead3ca89241ae9cb7e5c7eb1a6fab59104c8b2a"},"previous_names":["kenpowers/gulp-spawn-mocha"],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knpwrs%2Fgulp-spawn-mocha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knpwrs%2Fgulp-spawn-mocha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knpwrs%2Fgulp-spawn-mocha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knpwrs%2Fgulp-spawn-mocha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knpwrs","download_url":"https://codeload.github.com/knpwrs/gulp-spawn-mocha/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224014351,"owners_count":17241281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T05:14:43.646Z","updated_at":"2024-11-13T05:14:44.113Z","avatar_url":"https://github.com/knpwrs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gulp-spawn-mocha\n\n[![Dependency Status](https://img.shields.io/david/knpwrs/gulp-spawn-mocha.svg)](https://david-dm.org/knpwrs/gulp-spawn-mocha)\n[![devDependency Status](https://img.shields.io/david/dev/knpwrs/gulp-spawn-mocha.svg)](https://david-dm.org/knpwrs/gulp-spawn-mocha#info=devDependencies)\n[![Build Status](https://img.shields.io/travis/knpwrs/gulp-spawn-mocha.svg)](https://travis-ci.org/knpwrs/gulp-spawn-mocha)\n[![Code Coverage](https://img.shields.io/coveralls/knpwrs/gulp-spawn-mocha.svg)](https://coveralls.io/github/knpwrs/gulp-spawn-mocha)\n[![Npm Version](https://img.shields.io/npm/v/gulp-spawn-mocha.svg)](https://www.npmjs.com/package/gulp-spawn-mocha)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Badges](https://img.shields.io/badge/badges-7-orange.svg)](http://shields.io/)\n\nThis is a plugin for [gulp] which runs [Mocha] tests in a separate process from\nthe `gulp` process. Each time tests are run a new child process is created\nmeaning the test environment always starts cleanly, i.e., globals are reset as\nare non-enumerable properties defined on native prototypes via\n`Object.defineProperty`. This also means that if your tests crash the node\nprocess (e.g., `process.exit(-1)`.) then an `error` event is emitted rather than\nyour whole `gulp` process crashing (good for watching).\n\n## Usage\n\nUsage is according to this API:\n\n```javascript\nstream.pipe(\n  mocha({\n    // options\n  })\n);\n```\n\nThis plugin uses `mocha` version `^6.0.0`. The major version of this plugin will\nmatch the major version of `mocha`, which is a peer dependency of this plugin.\n\nThe plugin accepts these special options:\n\n- `bin`: a path to a `mocha` executable to use instead of the one this plugin\n  looks for by default. This is useful if you want to use a fork of `mocha`\n  which goes by a different name or a different executable altogether.\n- `env`: the environment variables that the child process will have access to\n  (key-value pairs, see [child_process::fork][fork]). These variables are\n  merged with your current environment variables and sent to the mocha\n  executable.\n- `cwd`: the working directory for the child process. This can be used to put\n  files that the test creates or reads from the working directory in a specific\n  directory, instead of the directory where you are running gulp from.\n- `execPath`: an alternative execution path to the Node.js instance.\n  If not specified, by default, [child_process::fork][fork] will spawn the new\n  Node.js instances using the [process::execPath][execpath] of the parent process.\n\nAll other options are properly prefixed with either `-` or `--` and passed to\nthe `mocha` executable. Any arguments which do not take a value (e.g., `c`,\n`colors`, or `debug`) should just have a value of `true`. Any arguments which\nhave dashes in the name can be specified by using camelCase (i.e., `debugBrk`\nfor `--debug-brk`, `inlineDiffs` for `--inline-diffs`, etc) so you don't have\nto use strings for the argument names. Please note that the `gc` option must\nbe specified as `exposeGc` (please see [issue #21][21]). For an example, see\nthis plugin's very own `gulpfile.js`:\n\n```javascript\nconst DEBUG = process.env.NODE_ENV === \"debug\",\n  CI = process.env.CI === \"true\";\n\nvar gulp = require(\"gulp\"),\n  mocha = require(\"./lib\");\n\ngulp.task(\"test\", function() {\n  return gulp.src([\"test/*.test.js\"], { read: false }).pipe(\n    mocha({\n      debugBrk: DEBUG,\n      r: \"test/setup.js\",\n      R: CI ? \"spec\" : \"nyan\",\n      istanbul: !DEBUG\n    })\n  );\n});\n\ngulp.task(\"default\", [\"test\"], function() {\n  gulp.watch(\"{lib,test}/*\", [\"test\"]);\n});\n```\n\nWith this setup the `nyan` reporter will be used in development and the `spec`\nreporter will be used in CI (Travis sets the `CI` environment variable to\n`true` automatically).\n\nThe `default` task will execute tests and watch for changes and execute tests\nwhenever a change is detected.\n\n### Conditional Arguments\n\nIf the value of an argument is falsy (but not `0`) then it will not be passed\nto `mocha`. This is useful, for example, if you want to enable debugging only\nwhen a certain environment variable is true. Example:\n\n```javascript\nconst DEBUG = process.env.NODE_ENV === \"debug\";\nstream.pipe(\n  mocha({\n    debugBrk: DEBUG,\n    istanbul: !DEBUG\n  })\n);\n```\n\n### Custom Environment Variables\n\nAs mentioned above an object provided underneath the `env` options key will\nallow you to specify a custom environment. This is useful, for example, to run\nyour tests in a different NODE_ENV than the default. Such a gulp task would\nlook like this:\n\n```javascript\nvar gulp = require(\"gulp\"),\n  mocha = require(\"gulp-spawn-mocha\");\n\ngulp.task(\"test\", function() {\n  return gulp.src([\"test/*.test.js\"]).pipe(\n    mocha({\n      env: { NODE_ENV: \"test\" }\n    })\n  );\n});\n```\n\nThese variables are merged with your current environment variables and sent to\nthe mocha executable.\n\n### Code Coverage\n\nBecause of the nature of this plugin launching an external process to run tests,\nthe standard coverage plugins for gulp will not work with this module. Starting\nin version `0.4.0` [Istanbul] is included in order to enable code coverage\nreports without having to instrument code on disk. You can use it by passing the\n`istanbul` option.\n\nSet `istanbul` to `true` if you want to use all the default settings:\n\n```javascript\ngulp.task(\"test\", function() {\n  return gulp.src([\"test/*.test.js\"]).pipe(\n    mocha({\n      istanbul: true\n    })\n  );\n});\n```\n\nThis will launch a process equivilant to:\n\n```\nistanbul cover -- _mocha\n```\n\nThe default settings of Istanbul output to a directory in the `cwd` called\n`coverage`.\n\nIf you want to pass options to Istanbul, you can do that as well:\n\n```javascript\ngulp.task(\"test\", function() {\n  return gulp.src([\"test/*.test.js\"]).pipe(\n    mocha({\n      istanbul: {\n        dir: \"path/to/custom/output/directory\"\n      }\n    })\n  );\n});\n```\n\nThis will launch a process equivilant to:\n\n```\nistanbul cover --dir path/to/custom/output/directory -- _mocha\n```\n\nThis will output to a directory called `path/to/custom/output/directory`.\n\nIstanbul, like `mocha`, supports a custom `bin` option so you can use a custom\nfork of Istanbul:\n\n```javascript\ngulp.task(\"test\", function() {\n  return gulp.src([\"test/*.test.js\"]).pipe(\n    mocha({\n      istanbul: {\n        dir: \"path/to/custom/output/directory\",\n        bin: require.resolve(\"isparta\") + \"/bin/isparta\"\n      }\n    })\n  );\n});\n```\n\nThis will launch a process equivilant to:\n\n```\n./node_modules/isparta/bin/isparta cover --dir path/to/custom/output/directory -- _mocha\n```\n\n#### Publishing Coverage Reports\n\nAssuming you are using [Travis] for CI and [Coveralls] for\npublishing code coverage reports it is very easy to automatically have Travis\npublish to Coveralls when tests are run successfully. First make sure you\ninstall and save the `coveralls` module as a dev dependency:\n\n```\nnpm i --save-dev coveralls\n```\n\nThen edit your `.travis.yml` to have an `after_success` command:\n\n```yaml\nlanguage: node_js\nnode_js:\n  - \"0.11\"\n  - \"0.10\"\nafter_success: ./node_modules/.bin/coveralls --verbose \u003c coverage/lcov.info\n```\n\nThe `coveralls` module requires no additional configuration to publish to\nCoveralls as long as both Travis and Coveralls are configured for the same\n_public_ repository. See [`node-coveralls`][ncov] for more details.\n\n### Output Reports to a File\n\nYou can pass `output` option to write a report to a writeable stream. If\n`output` is a string then a writeable stream will be created with `output` as\nits path. Note, if you are using `istanbul`, your reports content may contain\n`istanbul`'s result.\n\nUse file path:\n\n```js\ngulp.task(\"test\", function() {\n  return gulp.src([\"test/*.test.js\"], { read: false }).pipe(\n    mocha({\n      debugBrk: DEBUG,\n      r: \"test/setup.js\",\n      R: CI ? \"spec\" : \"nyan\",\n      istanbul: !DEBUG,\n      output: \"result.log\"\n    })\n  );\n});\n```\n\nUse file stream:\n\n```js\ngulp.task(\"test\", function() {\n  return gulp.src([\"test/*.test.js\"], { read: false }).pipe(\n    mocha({\n      debugBrk: DEBUG,\n      r: \"test/setup.js\",\n      R: CI ? \"spec\" : \"nyan\",\n      istanbul: !DEBUG,\n      output: fs.createWriteStream(\"result.log\", { flags: \"w\" })\n    })\n  );\n});\n```\n\n## This or `gulp-mocha`?\n\nThe original `gulp-mocha` is fine in most circumstances. If you need your\ntests to run as a separate process (or a separate process is simply your\npreference for the reasons specified above) or you need to use a custom\nversion of Mocha (e.g., a fork with bug fixes or custom functionality) then\nyou should use this plugin.\n\n## License\n\n[**MIT**](./LICENSE)\n\n[gulp]: http://gulpjs.com/ \"gulp.js\"\n[mocha]: http://mochajs.org/ \"Mocha\"\n[fork]: https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options \"child_process::fork\"\n[execpath]: https://nodejs.org/api/process.html#process_process_execpath \"process::execPath\"\n[istanbul]: https://github.com/gotwarlost/istanbul \"Istanbul\"\n[travis]: https://travis-ci.org/ \"Travis CI\"\n[coveralls]: https://coveralls.io/ \"Coveralls\"\n[ncov]: https://github.com/nickmerwin/node-coveralls \"node-coveralls\"\n[21]: https://github.com/knpwrs/gulp-spawn-mocha/issues/21 \"Issue 21: Setting `gc` option calls `mocha --gc` instead of `mocha -gc`\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknpwrs%2Fgulp-spawn-mocha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknpwrs%2Fgulp-spawn-mocha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknpwrs%2Fgulp-spawn-mocha/lists"}