{"id":15288930,"url":"https://github.com/zbigg/mocha-webdriver-runner","last_synced_at":"2025-10-04T16:04:42.312Z","repository":{"id":33142815,"uuid":"151637268","full_name":"zbigg/mocha-webdriver-runner","owner":"zbigg","description":"Run Mocha tests in browsers using Selenium WebDriver","archived":false,"fork":false,"pushed_at":"2024-05-20T13:23:33.000Z","size":1821,"stargazers_count":5,"open_issues_count":15,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-26T23:11:11.568Z","etag":null,"topics":["browser","javascript","mocha","selenium","selenium-webdriver","tdd","test-automation","testing","webdriver","webdriverjs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/zbigg.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":"2018-10-04T21:20:12.000Z","updated_at":"2024-09-23T10:18:54.000Z","dependencies_parsed_at":"2024-06-19T03:56:06.090Z","dependency_job_id":"35c47d66-388a-457d-be85-d1c2995849f0","html_url":"https://github.com/zbigg/mocha-webdriver-runner","commit_stats":{"total_commits":170,"total_committers":5,"mean_commits":34.0,"dds":"0.23529411764705888","last_synced_commit":"ff066276c8625613f676b5309fe29b7831606dd1"},"previous_names":["zbigg/mocha-selenium-runner"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbigg%2Fmocha-webdriver-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbigg%2Fmocha-webdriver-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbigg%2Fmocha-webdriver-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbigg%2Fmocha-webdriver-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zbigg","download_url":"https://codeload.github.com/zbigg/mocha-webdriver-runner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248674659,"owners_count":21143760,"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":["browser","javascript","mocha","selenium","selenium-webdriver","tdd","test-automation","testing","webdriver","webdriverjs"],"created_at":"2024-09-30T15:54:42.206Z","updated_at":"2025-10-04T16:04:37.289Z","avatar_url":"https://github.com/zbigg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mocha-webdriver-runner\n\n[![npm](https://img.shields.io/npm/v/mocha-webdriver-runner.svg?style=flat-square)](http://www.npmjs.com/package/mocha-webdriver-runner)\n[![Build status](https://github.com/zbigg/mocha-webdriver-runner/workflows/CI/badge.svg)](https://github.com/zbigg/mocha-webdriver-runner/actions)\n\nRun Mocha tests in browsers using Selenium WebDriver.\n\nInspired by [mocha-chrome](https://www.npmjs.com/package/mocha-chrome), but with following\nfeatures implemented from start:\n\n-   drives browser using Selenium WebDriver, so you can run tests on everything that selenium WebDriver supports. Hint: it supports everything (tm).\n-   runs reporters locally, in node environment so most of reporters (which are designed to work in node environment) should work out-of-box:\n    -   tested mocha builtins: spec, xunit, tap, etc ...\n    -   support for `mochawesome` (including usage of `addContext`)\n\nThat's it, have fun.\n\n## Install\n\n```\n$ npm install mocha-webdriver-runner\n```\n\n(Also ensure that you've got proper drivers or Selenium Grid available, see [Browser Driver](#browser-drivers) section below).\n\n## Usage\n\nPrepare your tests to run in browser as described on [Mocha website](https://mochajs.org/#running-mocha-in-the-browser).\n\nAdd `mocha-webdriver-runner` browser side client just after normal `mocha.js` `\u003cscript\u003e` tag:\n\n       \u003cscript src=\"../node_modules/mocha/mocha.js\"\u003e\u003c/script\n     + \u003cscript src=\"../node_modules/mocha-webdriver-runner/dist/mocha-webdriver-client.js\"\u003e\u003c/script\u003e\n\nRun the test suite against local browser:\n\n    SELENIUM_BROWSER=chrome npx mocha-webdriver-runner test/index.html\n\n    SELENIUM_BROWSER=firefox npx mocha-webdriver-runner test/index.html --reporter=tap\n\n(assuming your tests are in test/index.html).\n\nThe HTML test page works in two environments:\n * normal browser window - HTML report is generated in browser window as usual\n * when ran through `mocha-webdriver-runner`, report is forwarded to reporter running in node\n   (default is `spec`)\n\nSee `package.json` scripts and `test/sample-suite/index-headless.html` for reference.\n\n## Browser capabilities\n\nUse `-C key[=value]` (or `--capability`) options to set requested browser capabilities.\nValue may be plain string, or JSON value, examples:\n\n```\n-C browserName=firefox\n-C moz:firefoxOptions.args='[\"-headless\"]'\n-C browserName=chrome\n-C goog:chromeOptions.args='[\"--headless\", \"--window-size=300,300\"]'\n```\n\nConvenience shortcuts:\n\n| Shortcut option | Resolves to\n| -               | ----\n| `--headless-chrome`  | `-C browserName=chrome -C goog:chromeOptions.args='[\"--headless\"]'`\n| `--chrome`           | `-C browserName=chrome`\n| `--headless-firefox` | `-C browserName=firefox -C moz:firefoxOptions.args='[\"-headless\"]'`\n| `--firefox`          | `-C browserName=firefox`\n| `--edge`             | `-C browserName=MicrosoftEdge`\n| `--safari`           | `-C browserName=safari`\n\nUseful links:\n\n-   [Chrome driver capabilities](https://sites.google.com/a/chromium.org/chromedriver/capabilities)\n-   [Gecko driver capabilities](https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/Capabilities.html)\n-   [Selenium Capabilities](https://www.selenium.dev/documentation/legacy/desired_capabilities/)\n\nSelenium WebDriverJS accepts capabilities passed by environment variables as below:\n\n```\nSELENIUM_BROWSER=chrome\nSELENIUM_BROWSER=firefox:52\nSELENIUM_REMOTE_URL=http://my-selenium-grid:4444/wd/hub\n```\n\nSee [WebDriverJS Builder](https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_Builder.html)\n\n## Options\n\n```\n  -c, --config \u003cFILE\u003e                     config file (default: \".mocha-webdriver-runner.json\")\n  -C, --capability \u003cname[=value]\u003e         required browser capability\n  -O, --reporter-options \u003ck=v,k2=v2,...\u003e  reporter-specific options\n  -R, --reporter \u003cname\u003e                   specify the reporter to use (default: \"spec\")\n  -t, --timeout \u003cms\u003e                      set test-case timeout in milliseconds (default: 2000)\n  -L, --capture-console-log \u003cboolean\u003e     whether to capture console.log in browser context (default: true)\n  -g, --grep \u003cpattern\u003e                    only run tests/suites that match pattern\n  -V, --version                           output the version number\n  --chrome                                use Chrome\n  --headless-chrome                       use headless Chrome\n  --firefox                               use Firefox\n  --headless-firefox                      use headless Firefox\n  --safari                                use Safari\n  --edge                                  use Edge\n```\n\n## Config file\n\n`mocha-webdriver-runner` can load options from config file. Use `-c FILE` option to specify custom file.\nIf `-c` is not specified, `mocha-webdriver-runner` will attempt to load it from `.mocha-webdriver-runner.json`.\n\nConfig file, is JSON with, following properties:\n\n * `capabilities` - object representing `WebDriver` capabilities\n * all other CLI options are available as properties\n\nExample config for tests on Headless Chrome with no GPU and selecting only tests with `#performance` tag:\n```\n{\n    \"timeout\": 0,\n    \"grep\": \"#performance\n    \"capabilities\": {\n        \"browserName\": \"chrome\",\n        \"goog:chromeOptions\": {\n            \"args\": [\"--headless\", \"--disable-gpu=true\"]\n        }\n    }\n}\n```\n\n\n## Browser Drivers\n\nTesting against browser that runs on your desktop requires that proper drivers are installed in your environment.\n\n* Chrome - requires `chromedriver`\n   * available as NPM packet `chromedriver`\n   * documentation \u0026 manual download: http://chromedriver.chromium.org/\n* Firefox - requires `geckdriver`\n   * available as NPM packet `geckodriver`\n   * documentation \u0026 manual download: https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/\n* Safari - requires `safaridriver`\n   * SafariDriver (now) is installed by default, see https://developer.apple.com/documentation/webkit/testing_with_webdriver_in_safari\n\nFor `mocha-webdriver-runner` to work, particular webdriver must be installed somwehere in `PATH`.\n\nNote,  _convenience_ NPM packages -`chromedriver` and `geckdriver` - install them it to `./node_modules/.bin`, so if you run your tests via npm drivers are found automagically.\n\n## API\n\n### Node.Js\n\nFrom Node.js you can start tests using `runMochaWebDriverTest`.\n\n```javascript\n// in node.js context\nimport { runMochaWebDriverTest } from \"mocha-webdriver-runner\";\n\nconst webDriverCapabilities = {\n    browserName: \"firefox\"\n};\n\nrunMochaWebDriverTest(webDriverCapabilities, \"https://localhost:8080/test/index.html\")\n    .then(result =\u003e {\n        // result is boolean i.e ok or not ok\n        console.log(\"test result\", result ? \":)\" : \":(\");\n    })\n    .catch(error =\u003e {\n        // something bad happened with runner itself i.e webdriver error or something\n    });\n```\n\n### Browser general API\n\nBrowser module export global object `MochaWebdriverClient`.\n\nImport examples:\n\n```html\n\u003c!-- from CDN --\u003e\n\u003cscript src=\"https://unpkg.com/mocha-webdriver-runner/dist/mocha-webdriver-client.js\"\u003e\u003c/script\u003e\n\u003c!-- from local node_modules --\u003e\n\u003cscript src=\"../node_modules/mocha-webdriver-runner/dist/mocha-webdriver-client.js\"\u003e\u003c/script\u003e\n```\n\n`MochaWebdriverClient` API\n\n-   `addMochaSource(mocha)` - instruments `mocha` instance to send runner events back to\n    `mocha-selenium-runner` process.\n\n    Example:\n\n    ```javascript\n    mocha.setup({ ui: \"bdd\" });\n    MochaWebdriverClient.install(mocha);\n    // load sources\n    mocha.run();\n    ```\n\n-   `addWorkerSource(worker: Worker)` - forwards all `mocha-selenium-runner` related events from\n    `worker` back to `mocha-selenium-runner` process (requires properly initialized `mocha` in\n    `worker` context\n\n    Example:\n\n    ```javascript\n    const worker = new Worker(\"some-test-worker.js\");\n    MochaWebdriverClient.addWorkerSource(worker);\n    ```\n\nExamples:\n\n-   [basic tests running in browser](test/sample-suite/index-headless.html)\n-   [require.js based test runner](test/sample-suite/requirejs.html)\n-   [tests ran in worker](test/sample-suite/worker-test.html)\n-   [tests ran in worker in auto mode](test/sample-suite/worker-test-auto.html)\n-   [example library / coverage report](test/sample-lib/README.md)\n\n## Contribute\n\nPRs accepted.\n\n## License\n\nMIT © Zbigniew Zagórski\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzbigg%2Fmocha-webdriver-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzbigg%2Fmocha-webdriver-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzbigg%2Fmocha-webdriver-runner/lists"}