{"id":14967410,"url":"https://github.com/shellscape/mocha-chrome","last_synced_at":"2025-04-05T14:05:55.470Z","repository":{"id":22727662,"uuid":"97158040","full_name":"shellscape/mocha-chrome","owner":"shellscape","description":":coffee: Run Mocha tests using headless Google Chrome","archived":false,"fork":false,"pushed_at":"2023-03-21T09:34:17.000Z","size":281,"stargazers_count":75,"open_issues_count":4,"forks_count":30,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T13:06:17.854Z","etag":null,"topics":["chrome","command-line","command-line-tool","google","headless","headless-chrome","mocha","mocha-reporter","mocha-tests","terminal"],"latest_commit_sha":null,"homepage":"","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/shellscape.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/funding.yml","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},"funding":{"patreon":"shellscape","custom":"https://paypal.me/shellscape","liberapay":"shellscape"}},"created_at":"2017-07-13T19:30:14.000Z","updated_at":"2025-03-11T21:15:46.000Z","dependencies_parsed_at":"2024-06-18T13:39:42.771Z","dependency_job_id":"869e15f0-38a6-49b6-8071-bf345eb3f76e","html_url":"https://github.com/shellscape/mocha-chrome","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellscape%2Fmocha-chrome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellscape%2Fmocha-chrome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellscape%2Fmocha-chrome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellscape%2Fmocha-chrome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shellscape","download_url":"https://codeload.github.com/shellscape/mocha-chrome/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345852,"owners_count":20924102,"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":["chrome","command-line","command-line-tool","google","headless","headless-chrome","mocha","mocha-reporter","mocha-tests","terminal"],"created_at":"2024-09-24T13:38:01.179Z","updated_at":"2025-04-05T14:05:55.452Z","avatar_url":"https://github.com/shellscape.png","language":"JavaScript","readme":"[tests]: \thttps://img.shields.io/circleci/project/github/shellscape/mocha-chrome.svg\n[tests-url]: https://circleci.com/gh/shellscape/mocha-chrome\n\n[size]: https://packagephobia.now.sh/badge?p=mocha-chrome\n[size-url]: https://packagephobia.now.sh/result?p=mocha-chrome\n\n[![tests][tests]][tests-url]\n[![size][size]][size-url]\n[![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com)\n\n# mocha-chrome\n\n:coffee: Run Mocha tests using headless Google Chrome\n\n## Requirements\n\n`mocha-chrome` requires Node v8.0.0 or higher.\n\n`mocha-chrome` is a development tool, which means you can use tools like [NVM](https://github.com/creationix/nvm) and [nodenv](https://github.com/nodenv/nodenv) to manage your installed versions, and temporarily switch to v8+ to run tests on your machine. Most modern CI environments also support specifying the version of Node to run.\n\n## Getting Started\n\nTo begin, you'll need to install `mocha-chrome`:\n\n```console\n$ npm install mocha-chrome --save-dev\n```\n\nThen you'll need a local npm install of mocha:\n\n```console\n$ npm install mocha --save-dev\n```\n\nTo run the tests, you'll need an HTML file with some basics:\n\n```html\n\u003c!doctype\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003ctitle\u003eTest\u003c/title\u003e\n    \u003cmeta charset=\"utf-8\"\u003e\n    \u003clink rel=\"stylesheet\" href=\"../../node_modules/mocha/mocha.css\" /\u003e\n    \u003cscript src=\"../../node_modules/mocha/mocha.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"../../node_modules/chai/chai.js\"\u003e\u003c/script\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003cdiv id=\"mocha\"\u003e\u003c/div\u003e\n    \u003cscript\u003e\n      expect = chai.expect;\n\n      // add tests here\n\n      mocha.run();\n    \u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n\n```\n\nYou can then add your tests either through an external script file or inline within a `\u003cscript\u003e` tag. Running the tests is easy, either with the CLI binary, or programmatically.\n\n## CLI\n\n```console\n$ mocha-chrome --help\n\n  Usage\n    $ mocha-chrome \u003cfile.html\u003e [options]\n\n  Options\n    --chrome-flags              A JSON string representing an array of flags to pass to Chrome\n    --chrome-launcher           Chrome launcher options (see https://github.com/GoogleChrome/chrome-launcher#launchopts)\n    --ignore-console            Suppress console logging\n    --ignore-exceptions         Suppress exceptions logging\n    --ignore-resource-errors    Suppress resource error logging\n    --log-level                 Specify a log level; trace, debug, info, warn, error\n    --mocha                     A JSON string representing a config object to pass to Mocha\n    --no-colors                 Disable colors in Mocha's output\n    --reporter                  Specify the Mocha reporter to use\n    --timeout                   Specify the test startup timeout to use\n    --version\n\n  Examples\n  $ mocha-chrome test.html --no-colors\n  $ mocha-chrome test.html --reporter dot\n  $ mocha-chrome test.html --mocha '\\{\"ui\":\"tdd\"\\}'\n  $ mocha-chrome test.html --chrome-flags '[\"--some-flag\", \"--and-another-one\"]'\n  $ mocha-chrome test.html --chrome-launcher.maxConnectionRetries=10\n```\n\n## Events\n\n`mocha-chrome` is technically an event emitter. Due to the asynchronous nature of nearly every interaction with headless Chrome, a simple event bus is used to handle actions from the browser. You have access to those events if running `mocha-chrome` programatically.\n\nExample usage can be found in both [test.js](test/test.js) and [bin/mocha-chrome](bin/mocha-chrome).\n\n#### `config`\n\n  Fired to indicate that `mocha-chrome` should configure mocha.\n\n#### `ended`\n\n  Fired when all tests have ended.\n\n##### Parameters\n  `stats` : `object` - A Mocha stats object. eg:\n\n  ```js\n  {\n    suites: 1,\n    tests: 1,\n    passes: 1,\n    pending: 0,\n    failures: 0,\n    start: '2017-08-03T02:12:02.007Z',\n    end: '2017-08-03T02:12:02.017Z',\n    duration: 10\n  }\n  ```\n\n#### `ready`\n\n  Fired to indicate that the mocha script in the client has been loaded.\n\n#### `resourceFailed`\n\n  Fired when a resource fails to load.\n\n  ##### Parameters\n  `data` : `object` - An object containing information about the resource. eg:\n\n  ```js\n  { url, method, reason }\n  ```\n\n#### `started`\n\n  Fired when a resource fails to load.\n\n  ##### Parameters\n  `tests` : `number` - The number of tests being run.\n\n#### `width`\n\n  Fired to indicate that `mocha-chrome` should inform mocha of the width of the current console/terminal.\n\n## Limitations\n\n### Reporters\n\nReporters are limited to those which don't use `process.stdout.write` to manipulate terminal output. eg. `spec`, `xunit`, etc. Examples of reporters which don't presently produce expected output formatting include `dot` and `nyan`. The cause of this limitation is the lack of a good means to pipe Mocha's built-in `stdout.write` through the Chrome Devtools Protocol to `mocha-chrome`.\n\n### Third-Party Reporters\n\nThird party reporters are not currently supported, but support is planned. Contribution on that effort is of course welcome.\n\n### Cookies and the `file://` Protocol\n\nChrome has long-since disabled cookies for files loaded via the `file://` protocol. The once-available `--enable-file-cookies` has been removed and we're left with few options. If you're in need of cookie support for your local-file test, you may use the following snippet, which will shim `document.cookie` with _very basic_ support:\n\n```js\n  Object.defineProperty(document, 'cookie', {\n    get: function () {\n      return this.value || '';\n    },\n    set: function (cookie) {\n      cookie = cookie || '';\n\n      const cutoff = cookie.indexOf(';');\n      const pair = cookie.substring(0, cutoff \u003e= 0 ? cutoff : cookie.length);\n      const cookies = this.value ? this.value.split('; ') : [];\n\n      cookies.push(pair);\n\n      return this.value = cookies.join('; ');\n    }\n  });\n```\n\n## Continuous Integration\n\n### Circle CI\n\nRunning on Circle CI requires that Chrome is installed and running in the container your tests are running within. Please refer to this article for details: https://discuss.circleci.com/t/installing-chrome-inside-of-your-docker-container/9067. Alternatively, you can use a pre-built CircleCI image with browsers installed. You'll have to choose a tag with the `-browsers` suffix from the [full tag list](https://circleci.com/docs/2.0/docker-image-tags.json).\n\n### Travis CI\n\nPlease refer to the _\"Running it all on Travis CI\"_ portion of the guide on [Automated testing with Headless Chrome](https://developers.google.com/web/updates/2017/06/headless-karma-mocha-chai) from\nGoogle. Though the article primarily addresses Karma, the setup for Travis CI is\nidentical.\n\nAs of January 8th, 2018, Travis CI has upgraded from Trusty -\u003e Xenial to address the [Meltdown](https://en.wikipedia.org/wiki/Meltdown_(security_vulnerability)) security vulnerability. There are issues with Chrome in Xenial that can currently be worked around with `sudo: required`. At some point this workaround may be removable. For the near term, please add `sudo: required` to Travis CI configuration files. See [travis-ci/travis-ci#8836](travis-ci/travis-ci#8836). Credit: [@smalls](https://github.com/shellscape/mocha-chrome/pull/21).\n\n\n\n## Testing mocha-chrome\n\n```console\n$ npm test\n```\n\nYep, that's it.\n\n## Contributing\n\nWe welcome your contributions! Please have a read of [CONTRIBUTING](.github/CONTRIBUTING.md).\n\n## Attribution\n\nI'd like to thank @nathanboktae for his work on [mocha-phantomjs](https://github.com/nathanboktae/mocha-phantomjs) and [mocha-phantomjs-core](https://github.com/nathanboktae/mocha-phantomjs-core); two projects I've used extensively over the years, and from which the inspiration for this module originates. Many of the nuances of working with mocha in a hosted or connected browser environment were solved within `mocha-phantomjs-core` and I am personally grateful.\n","funding_links":["https://patreon.com/shellscape","https://paypal.me/shellscape","https://liberapay.com/shellscape"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellscape%2Fmocha-chrome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshellscape%2Fmocha-chrome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellscape%2Fmocha-chrome/lists"}