{"id":16759891,"url":"https://github.com/corevo/docker-compose-testkit","last_synced_at":"2025-07-17T18:31:37.645Z","repository":{"id":46477353,"uuid":"415263001","full_name":"corevo/docker-compose-testkit","owner":"corevo","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-09T10:37:36.000Z","size":1465,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-16T12:19:08.271Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/corevo.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}},"created_at":"2021-10-09T09:28:56.000Z","updated_at":"2024-10-09T10:37:41.000Z","dependencies_parsed_at":"2024-04-25T10:48:12.707Z","dependency_job_id":null,"html_url":"https://github.com/corevo/docker-compose-testkit","commit_stats":{"total_commits":35,"total_committers":1,"mean_commits":35.0,"dds":0.0,"last_synced_commit":"bb127738c22b63f6615dbdd99b0eb74bef22aa7c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/corevo/docker-compose-testkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corevo%2Fdocker-compose-testkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corevo%2Fdocker-compose-testkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corevo%2Fdocker-compose-testkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corevo%2Fdocker-compose-testkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/corevo","download_url":"https://codeload.github.com/corevo/docker-compose-testkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corevo%2Fdocker-compose-testkit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265645373,"owners_count":23804183,"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-10-13T04:09:16.991Z","updated_at":"2025-07-17T18:31:37.372Z","avatar_url":"https://github.com/corevo.png","language":"TypeScript","readme":"# docker-compose-testkit\n\nA library designed for TDD while leveraging docker compose.  \n\n`docker-compose-testkit` helps writing tests by automating the creation and deletions of docker compose environments via test code.\nEach test suite (or test!), may create it's own isolated compose network to test against, helping create stronger tests.\n\n## Installation\n\nThe library can work with any test runner, or just via code, the only requirement is docker compose v2 installed on the machine.\n\n```sh\n$ npm i --save-dev docker-compose-testkit\n```\n\nOr alternatively\n\n```sh\n$ yarn add -D docker-compose-testkit\n```\n\n## Usage\n\nGiven the following `docker-compose.yml` file\n```yaml\nversion: '3'\nservices:\n  nginx:\n    image: nginx:latest\n    ports:\n      - 80\n```\n\nThe following test will up the network before all the tests, and tear it down once the tests finish\n```ts\nimport path from 'path'\nimport {fileURLToPath} from 'url'\nimport dockerCompose from 'docker-compose-testkit'\n\ndescribe('testing using docker compose', () =\u003e {\n  const pathToCompose = path.join(\n    path.dirname(fileURLToPath(import.meta.url)),\n    'docker-compose.yml',\n  )\n  const compose = dockerCompose(pathToCompose)\n\n  beforeAll(compose.setup)\n  afterAll(compose.teardown)\n\n  it('should send a request to nginx', async () =\u003e {\n    // translates the internal address (i.e. nginx:80) to host's (e.g. 0.0.0.0:23424)\n    const nginxAddress = await compose.getAddressForService('nginx', 80)\n    expect((await fetch(`http://${nginxAddress}/`)).ok).to.be.true()\n  })\n})\n```\n\n## API\n\n### dockerCompose(pathToCompose, options?)\nCreates the compose object that will manage the network, once it is set up.\n\n#### [options](src/docker-compose-testkit.ts#L26)\n\nSpecific options to set for the network and containers\n\n`servicesToStart: string[]` - A list of cherry-picked services to start with the network (default: everything).\n\n`tailServices: string` - Name of a service to start tailing its logs immediately, logs will be printed to stdout regardless of the original file descriptor.\n\n`projectName: string` - Can be used to reconnect to an existing network from a previous run.\n\n`env: object` - Key value object that will set the environment variables for the compose commands, by default containers will not have access to the host's env vars.\n\n`orphanCleanup: boolean` - Wether or not to perform cleanup for containers that might have been left by a previous run (default `true`).\n\n`cleanup: boolean` - Wether or not to perform a cleanup of the network after the test complete (disables the teardown) (default: `true`).\n\n`pullImages: boolean` - Attempt to pull the images prior to `docker compose up` (default: `false`).\n\n`forceKill: boolean` - Send a `SIGKILL` to all containers before running `docker compose down`, this can speed up the teardown significantly (default: `true`).\n\n`containerRetentionInMinutes: number` - How long to keep this network from being picked up by the orphan cleanup, use alongside with `cleanup: false` to retain a network for debugging purposes (default: 5 minutes).\n\nReturns [`Promise\u003cCompose\u003e`](src/docker-compose-testkit.ts#L38).\n\n### compose.projectName\n\nA string representing the generated docker compose project name, pass it again to `dockerCompose(pathToCompose, {projectName})` to reconnect to an existing network.\n\n### compose.pathToCompose\n\nThe path to the compose file as given to the `dockerCompose(pathToCompose)`\n\n### compose.setup()\n\nRuns cleanup for orphaned containers, networks and volumes. And then starts up the new network.\n\nReturns `Promise`.\n\n### compose.teardown()\n\nTears down the current network.\n\nReturns `Promise`.\n\n### compose.getAddressForService(serviceName: string, options?)\n\nTranslates the internal address of a given service to the exposed one on the host's machine. For example `nginx:80` to `0.0.0.0:52736`.\n\nThe function will attempt to contact the service (similarly to Kubernetes liveness probe), to gauge wether the service is ready to accept connections.\n\nReturns `Promise\u003cstring\u003e`\n\n#### options\n\n`healthCheck: undefined | false | string | (address, AbortError) =\u003e Promise\u003cvoid\u003e` - A custom health check function that will be retried to gauge when the service is ready to be used.\n\n- `undefined` is the default, will attempt to send a GET request to `/`.\n- `false` disables the health check, the function will return with the address as normal.\n- `string` changes the path of the GET request, can be used for `/healthz`.\n- `function` a custom function that defines the health check, it will be retried automatically, unless an `AbortError` is sent. Functions arguments:\n  - address: string - the addres of the service to test\n  - AbortError: (message: string) =\u003e AbortError - functions that creates an error that will stop the retries immediately\n\n`fiveHundedStatusIsOk: boolean` - Wether to consider `\u003e500` status codes as healthy (default: `false`).\n\n`maxRetries: number` - How many times to retry the health check, the retries have exponential backoff (default: `10`).\n\n### compose.getInernalIpForService\n\nTranslates the inernal hostname (i.e. `nginx`) to the internal network IP, for example `172.17.0.1`.\n\nReturns `Promise\u003cstring\u003e`.\n\n### compose.listContainers()\n\nGets a list of the containers in the network.\n\nReturns `Promise\u003cContainer[]\u003e`.\n\n### compose.containerExists(serviceName: string)\n\nChecks if a container exists for a specific service.\n\nReturns `Promise\u003cboolean\u003e`.\n\n### compose.getLogsForService(serviceName: string)\n\nReturns all the logs by a given service name, `stdout` and `stderr` will be interleaved.\n\nReturns `Promise\u003cstring\u003e`\n\n### compose.waitForServiceToExit(serviceName: string, options)\n\nWaits for a running service to finish and exit.\n\nReturns `Promise`\n\n#### options\n\n`anyExitCode: boolean` - Wether to throw if the exit code is not `0` (default: `false`).\n\n`timeout: number` - Total timeout to wait for in milliseconds (default: 5 minutes).\n\n### compose.runService(serviceName: string, commandWithArgs: string[])\n\nRuns a one-off command in a service (e.g. `docker compose run`).\n\n`commandWithArgs` - An array of the command and arguments for it.\n\nReturns [`Promise\u003cExecaReturnValue\u003e`](https://github.com/sindresorhus/execa#execafile-arguments-options)\n\n### compose.startService(serviceName: string)\n\nStarts a service in the network (e.g. `docker compose start`).\n\nReturns `Promise`.\n\n### compose.stopService(serviceName: string)\n\nStops a service in the network (e.g. `docker compose stop`).\n\nReturns `Promise`.\n\n### compose.pauseService(serviceName: string)\n\nPauses a service in the network (e.g. `docker compose pause`).\n\nReturns `Promise`.\n\n### compose.unpauseService(serviceName: string)\n\nUnpauses a service in the network (e.g. `docker compose unpause`).\n\nReturns `Promise`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorevo%2Fdocker-compose-testkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorevo%2Fdocker-compose-testkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorevo%2Fdocker-compose-testkit/lists"}