{"id":15020898,"url":"https://github.com/theintern/digdug","last_synced_at":"2025-04-05T18:10:33.006Z","repository":{"id":17189719,"uuid":"19957276","full_name":"theintern/digdug","owner":"theintern","description":"A JavaScript library for launching WebDriver service tunnels.","archived":false,"fork":false,"pushed_at":"2023-11-01T01:25:58.000Z","size":2288,"stargazers_count":44,"open_issues_count":7,"forks_count":28,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-29T17:11:10.298Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://theintern.github.io/digdug/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theintern.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-05-19T20:51:27.000Z","updated_at":"2022-11-28T16:18:27.000Z","dependencies_parsed_at":"2023-01-13T19:12:19.921Z","dependency_job_id":"3a818732-509b-493c-84d2-7fe9c8066692","html_url":"https://github.com/theintern/digdug","commit_stats":null,"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theintern%2Fdigdug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theintern%2Fdigdug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theintern%2Fdigdug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theintern%2Fdigdug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theintern","download_url":"https://codeload.github.com/theintern/digdug/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378149,"owners_count":20929297,"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-09-24T19:55:49.434Z","updated_at":"2025-04-05T18:10:32.987Z","avatar_url":"https://github.com/theintern.png","language":"TypeScript","funding_links":[],"categories":["Applications"],"sub_categories":[],"readme":"# Dig Dug\n\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- start-github-only --\u003e\n![Build status](https://github.com/theintern/digdug/actions/workflows/ci.yml/badge.svg)\n[![npm version](https://badge.fury.io/js/@theintern%2Fdigdug.svg)](https://badge.fury.io/js/@theintern%2Fdigdug)\n[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/theintern/digdug.svg)](http://isitmaintained.com/project/theintern/digdug \"Average time to resolve an issue\")\n[![Percentage of issues still open](http://isitmaintained.com/badge/open/theintern/digdug.svg)](http://isitmaintained.com/project/theintern/digdug \"Percentage of issues still open\")\n\n\u003cbr\u003e\u003cp align=\"center\"\u003e\u003cimg src=\"https://cdn.rawgit.com/theintern/digdug/master/docs/logo.svg\" alt=\"Dig Dug logo\" height=\"90\"\u003e\u003c/p\u003e\u003cbr\u003e\n\u003c!-- end-github-only --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\nDig Dug is a library for downloading and managing WebDriver service tunnels,\nalong with Selenium and individual WebDrivers.\n\n[![Intern](https://theintern.io/images/intern-v4.svg)](https://github.com/theintern/intern/)\n\n## Configuration\n\nDig Dug can connect to an existing local WebDriver or Selenium server, manage a\nlocal Selenium server, or connect to various remote cloud testing systems.\n\n### Local server\n\nUse [NullTunnel] to connect to an already-running server such as Selenium or a\nstandalone ChromeDriver instance. NullTunnel, as its name suggests, essentially\nnulls out most of the default functionality in Tunnel, such as the `download`\nmethod (used to download a service tunnel binary). For example, calling `start`\non any of the other tunnel classes would download the necessary tunnel binaries\nand spawn a child process, but calling `start` on a NullTunnel does nothing\n(with the assumption that the tunnel has already been started).\n\n### Managed Selenium server\n\nDig Dug can manage a local Selenium server with its [SeleniumTunnel]. By default\nthe tunnel will download a recent version of Selenium and ChromeDriver. The most\ncommonly used options for the Selenium tunnel are `version` and `drivers`. The\nversion option simply sets the version of Selenium to use, such as `'3.4.0'`.\nThe `drivers` option tells SeleniumTunnel which drivers to download, and\noptionally which versions to use. For example, to configure SeleniumTunnel to\nuse geckodriver 0.18.0 and the default version of ChromeDriver with Selenium\n3.5.2:\n\n```js\nconst tunnel = new SeleniumTunnel({\n  version: '3.5.2',\n  drivers: [\n    'chrome',\n    {\n      name: 'firefox',\n      version: '0.18.0'\n    }\n  ]\n});\n```\n\nTo determine what are the most recent versions of Selenium and the various\nwebdrivers, Dig Dug will first attempt to download a version manifest from\n`https://theintern.github.io`. If this fails, Dig Dug will fall back to the\nmanifest contained in the package. The actual location used to download the\nmanifest can be controlled via the `webDriverConfigUrl` property on\nSeleniumTunnel. Set the property to `false` to prevent SeleniumTunnel from\ntrying to download the manifest.\n\n### Cloud testing services\n\nDig Dug supports the following cloud testing services:\n\n- [BrowserStack](http://www.browserstack.com)\n- [CrossBrowserTesting](http://www.crossbrowsertesting.com)\n- [Sauce Labs](http://www.saucelabs.com)\n- [TestingBot](http://www.testingbot.com)\n\nIn many cases, the only configuration you’ll need to do to create a tunnel is\nprovide authentication data. This can be provided via options to a Tunnel\nconstructor or via environment variables. The service tunnels use the following\nenvironment variables:\n\n| Tunnel class                | Environment variables                              |\n| --------------------------- | -------------------------------------------------- |\n| `BrowserStackTunnel`        | `BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY` |\n| `CrossBrowserTestingTunnel` | `CBT_USERNAME`, `CBT_APIKEY`                       |\n| `SauceLabsTunnel`           | `SAUCE_USERNAME`, `SAUCE_ACCESS_KEY`               |\n| `TestingBotTunnel`          | `TESTINGBOT_KEY`, `TESTINGBOT_SECRET`              |\n\nOther properties, such as the local port the tunnel should serve on or the URL\nof a proxy server the tunnel should go through, can be passed to a tunnel\nconstructor or set on a tunnel instance. See the API docs for [Tunnel] and its\nsubclasses for available properties:\n\n- [BrowserStackTunnel](https://theintern.io/docs.html#Dig%20Dug/2/api/BrowserStackTunnel/browserstackproperties)\n- [CrossBrowserTestingTunnel](https://theintern.io/docs.html#Dig%20Dug/2/api/CrossBrowserTestingTunnel/crossbrowsertestingproperties)\n- [SauceLabsTunnel](https://theintern.io/docs.html#Dig%20Dug/2/api/SauceLabsTunnel/saucelabsproperties)\n- [SeleniumTunnel](https://theintern.io/docs.html#Dig%20Dug/2/api/SeleniumTunnel/seleniumproperties)\n- [TestingBotTunnel](https://theintern.io/docs.html#Dig%20Dug/2/api/TestingBotTunnel/testingbotproperties)\n\n## Usage\n\nTo create a new tunnel, import the desired tunnel class, create a new instance,\nand call its `start` method. `start` returns a Promise that resolves when the\ntunnel has successfully started. For example, to create a new Sauce Labs tunnel:\n\n```js\nimport SauceLabsTunnel from '@theintern/digdug/SauceLabsTunnel';\nconst tunnel = new SauceLabsTunnel();\ntunnel.start().then(() =\u003e {\n  // interact with the WebDriver server at tunnel.clientUrl\n});\n```\n\nOnce a tunnel has been started, a test runner can interact with it as described\nin the service’s documentation. For example, the Sauce Labs and TestingBot\nexecutables start a WebDriver server on localhost that the test client\ncommunicates with, while a test client will connect to `hub.browserstack.com`\nafter the tunnel has started to use BrowserStack.\n\nThe tunnel classes also provide a `sendJobState` convenience method to let the\nremote service know whether a test session passed or failed. This method accepts\na session ID and an object containing service-specific data, and it returns a\nPromise that resolves if the job state was successfully updated.\n\n```js\ntunnel.sendJobState(sessionId, { success: true });\n```\n\nWhen testing is finished, call the tunnel’s `stop` method to cleanly shut it\ndown. This method returns a Promise that is resolved when the service tunnel\nexecutable has exited.\n\n```js\ntunnel.stop().then(() =\u003e {\n  // the tunnel has been shut down\n});\n```\n\n## Utilities\n\nDig Dug includes a utility script, `digdugEnvironmnents`, that will display all\nthe environments provided by a remote testing service.\n\n```\n$ ./node_modules/.bin/digdugEnvironments SauceLabsTunnel\n{\"platform\":\"OS X 10.9\",\"browserName\":\"firefox\",\"version\":\"4\"}\n{\"platform\":\"OS X 10.9\",\"browserName\":\"firefox\",\"version\":\"5\"}\n{\"platform\":\"OS X 10.9\",\"browserName\":\"firefox\",\"version\":\"6\"}\n{\"platform\":\"OS X 10.9\",\"browserName\":\"firefox\",\"version\":\"7\"}\n{\"platform\":\"OS X 10.9\",\"browserName\":\"firefox\",\"version\":\"8\"}\n{\"platform\":\"OS X 10.9\",\"browserName\":\"firefox\",\"version\":\"9\"}\n{\"platform\":\"OS X 10.9\",\"browserName\":\"firefox\",\"version\":\"10\"}\n...\n```\n\nNote that BrowserStackTunnel requires that the `BROWSERSTACK_ACCESS_KEY` and\n`BROWSERSTACK_USERNAME` environment variables exist and are set to a user’s\naccount access key and username. The other tunnels do not (currently) require\nauthentication to request an environment list.\n\n## More information\n\n- [API documentation](https://theintern.io/docs.html#Dig%20Dug/2/api/BrowserStackTunnel)\n\n\u003c!-- start-github-only --\u003e\n\n## License\n\nDig Dug is a JS Foundation project offered under the [New BSD](LICENSE) license.\n\n© [SitePen, Inc.](http://sitepen.com) and its\n[contributors](https://github.com/theintern/digdug/graphs/contributors)\n\n\u003c!-- end-github-only --\u003e\n\n\u003c!-- doc-viewer-config\n{\n    \"api\": \"docs/api.json\"\n}\n--\u003e\n\n[nulltunnel]: https://theintern.io/docs.html#Dig%20Dug/2/api/NullTunnel\n[seleniumtunnel]: https://theintern.io/docs.html#Dig%20Dug/2/api/SeleniumTunnel\n[tunnel]: https://theintern.io/docs.html#Dig%20Dug/2/api/Tunnel\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheintern%2Fdigdug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheintern%2Fdigdug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheintern%2Fdigdug/lists"}