{"id":19856854,"url":"https://github.com/polymer/koa-karma-proxy","last_synced_at":"2025-10-08T01:52:58.093Z","repository":{"id":43437402,"uuid":"196283608","full_name":"Polymer/koa-karma-proxy","owner":"Polymer","description":"Simplified coordination of karma and upstream proxy server using the koa web framework.","archived":false,"fork":false,"pushed_at":"2025-04-09T13:36:02.000Z","size":347,"stargazers_count":4,"open_issues_count":27,"forks_count":4,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-02T02:38:36.747Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Polymer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2019-07-10T22:37:24.000Z","updated_at":"2024-05-16T22:09:29.000Z","dependencies_parsed_at":"2025-05-02T02:48:02.747Z","dependency_job_id":null,"html_url":"https://github.com/Polymer/koa-karma-proxy","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Polymer/koa-karma-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polymer%2Fkoa-karma-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polymer%2Fkoa-karma-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polymer%2Fkoa-karma-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polymer%2Fkoa-karma-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Polymer","download_url":"https://codeload.github.com/Polymer/koa-karma-proxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Polymer%2Fkoa-karma-proxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266738789,"owners_count":23976472,"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","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-12T14:16:46.308Z","updated_at":"2025-10-08T01:52:53.052Z","avatar_url":"https://github.com/Polymer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# koa-karma-proxy\n\nSimplified coordination of [karma](https://karma-runner.github.io/) and upstream proxy server using the [koa](https://koajs.com) web framework.\n\n## Overview\n\nThis project came about because of the need to run a proxy server to perform on-demand transformations to responses from a karma server.  In principle this is straightforward as long as the karma and proxy server ports were reliably fixed.  When configuring karma, you have to be able to tell it what port the upstream proxy server is running on-- and you have to know what port the karma server is running on to direct requests from the proxy server.\n\nThe problem is that karma does not have a reliably fixed port, because karma will search for an available port when the default one is in use and then bind to that.  Because of the  mutual dependency on port knowledge between karma and the proxy server, some magic is required to slot in the karma server's address into the running proxy server after it starts up.\n\nThis library coordinates this process behind the scenes so your setup doesn't require a bunch of boilerplate with listeners and hooks to wire everything up.\n\n## Usage\n\nFirst, you'll need to install it, most likely as a `devDependency` of your `npm` package/application:\n\n```sh\n$ npm install --save-dev koa-karma-proxy\n```\n\nCreate a file called `karma.proxy.js` and export a function that returns a Koa app, which will define your proxy server. Be sure to slot in the provided proxy to karma, which is the single given parameter, named \"karma\" in the example below:\n\n```js\nconst Koa = require('koa');\nconst someMiddleaware = require('./some-middleware.js');\nmodule.exports = (karma) =\u003e new Koa().use(someMiddleware).use(karma);\n```\n\nIn the following example, we'll use the [`koa-node-resolve`](https://github.com/Polymer/koa-node-resolve) package to translate node bare module specifiers to relative paths on-the-fly. Please note that we mount the nodeResolve middleware specifically to the `/base` sub-path, since that is where karma serves our test, source and `node_modules` files from:\n\n```js\nconst Koa = require('koa');\nconst mount = require('koa-mount');\nconst {nodeResolve} = require('koa-node-resolve');\nmodule.exports = (karma) =\u003e new Koa()\n    .use(mount('/base', nodeResolve())\n    .use(karma);\n```\n\nUse the `karma-proxy` wrapper script exactly as you'd use `karma` executable:\n\n```sh\n$ npx karma-proxy start\n```\n\nThis will:\n\n1. find an open port for the proxy server.\n2. start the proxy server, listening on that port.\n3. start karma.  (identical to `karma start`)\n4. wait for karma to confirm the port it is listening on.\n5. configure the proxy middleware to start directing requests to karma.\n\nThe wrapper supports two optional flags in addition to all the ones in the standard `karma` CLI:\n\n - `--proxyFile` to point to a file other than `karma.proxy.js`.\n - `--proxyAddress` to specify a host name/IP for the proxy to listen on other than the default `0.0.0.0`.\n - `--proxyHostname` to specify a host name/IP to direct browsers to other than the default `localhost`.\n - `--proxyPort` to specify a starting port other than the default `9876` to start the upstream proxy server on.\n\nPlease note, when using `npx`, flags given to `karma-proxy` should follow a `--` separator so they are not treated as `npx` flags:\n```sh\n$ npx karma-proxy start -- --proxyFile ./lib/my-proxy.js --proxyPort 30330\n```\n\n## Advanced Usage\n\nYou don't have to use `karma-proxy` as an executable from the command-line.  It exposes everything you need to leverage within your own code:\n\n```ts\nconst Koa = require('koa');\nconst mount = require('koa-mount');\nconst {join} = require('path');\nconst {start} = require('koa-karma-proxy');\nconst {nodeResolve} = require('koa-node-resolve');\n\n(async () =\u003e {\n  const {upstreamProxyPort, karmaPort} =\n    await start((karma) =\u003e new Koa()\n      .use(mount('/base', nodeResolve())\n      .use(karma), {\n        // Karma config options\n        configFile: join(__dirname, '../karma.conf.js'),\n        singleRun: true\n      });\n  console.log(`Upstream Port ${upstreamProxyPort}`);\n  console.log(`Karma Port ${karmaPort}`);\n})();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolymer%2Fkoa-karma-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolymer%2Fkoa-karma-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolymer%2Fkoa-karma-proxy/lists"}