{"id":17342557,"url":"https://github.com/natural-intelligence/docker-compose-mocha","last_synced_at":"2025-04-14T19:44:26.358Z","repository":{"id":20907884,"uuid":"90744261","full_name":"Natural-Intelligence/docker-compose-mocha","owner":"Natural-Intelligence","description":"A tool used to create an isolated environment for services which are Docker-ized based on services found inside a given docker-compose.yml file when running Docker Compose tool.","archived":false,"fork":false,"pushed_at":"2021-12-06T09:44:31.000Z","size":150,"stargazers_count":7,"open_issues_count":7,"forks_count":4,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-04-14T21:54:26.724Z","etag":null,"topics":["automation","chai","ci","docker","docker-compose","mocha","testing"],"latest_commit_sha":null,"homepage":null,"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/Natural-Intelligence.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}},"created_at":"2017-05-09T12:40:59.000Z","updated_at":"2023-05-24T11:46:54.000Z","dependencies_parsed_at":"2022-08-07T09:16:24.249Z","dependency_job_id":null,"html_url":"https://github.com/Natural-Intelligence/docker-compose-mocha","commit_stats":null,"previous_names":["natural-intelligence/docker-compose-tool"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Natural-Intelligence%2Fdocker-compose-mocha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Natural-Intelligence%2Fdocker-compose-mocha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Natural-Intelligence%2Fdocker-compose-mocha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Natural-Intelligence%2Fdocker-compose-mocha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Natural-Intelligence","download_url":"https://codeload.github.com/Natural-Intelligence/docker-compose-mocha/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248949970,"owners_count":21188180,"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":["automation","chai","ci","docker","docker-compose","mocha","testing"],"created_at":"2024-10-15T16:06:14.024Z","updated_at":"2025-04-14T19:44:26.313Z","avatar_url":"https://github.com/Natural-Intelligence.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://umbrella.s3.naturalint.com/opensource/docker-compose-mocha/ni-eng-strip.jpg\" alt=\"NI Engineering\"\u003e\n\n# Docker Compose Mocha\n\nA tool used to create an isolated environment for services which are Docker-ized\nbased on services found inside a given docker-compose.yml file when run through the Docker Compose binary.\n\nThis can be particularly useful when you want to setup other services with end to end testing before your application starts to run it's test suite.\n\nOne thing to note: this tool is meant to be used with any testing framework (not necessarily Mocha) although the following examples\nare based on Mocha (due to it's popularity).\n\nDocker and CI/CD are incredibly important for us at \u003ca target=\"_blank\" href=\"http://naturalint.com/\"\u003eNatural Intelligence\u003c/a\u003e, as we have a large micro-service oriented system serving listings in more than 100 different fields. In addition, we are also \u003ca href=\"http://naturalint.com/careers\"\u003ehiring talented engineers\u003c/a\u003e to help us grow as a technological pioneers\n\n## Node versions supported\nThis package supports Node v6 and higher\n\n## Purpose\nThis package is solely for testing purposes for building CI/CD pipelines using Docker and can be used\nin combination with any language as long as your service is wrapped in a Docker image.\n\nYou will however need to orchestrate your CI/CD flow using Node (and possibly bash/zsh)\n\n## Installation\nInside your project directory type the following code:\n\n### When using npm\n```bash\n$ npm i docker-compose-mocha --save-dev\n```\n\n### When using yarn\n```bash\n$ yarn add docker-compose-mocha --dev\n```\n\n## Cleanup logic\nThe compose tool has a cleanup logic against mocha before and after functions.\nbefore:\nFull environment cleanup of all containers, networks, volumes etc... (Start tests with clean state).\nFull cleanup uses environment variable: `process.env.CONTAINER_STALE_MIN` parameter (with 0 minutes default value).\nIt means that every containers/networks created by the tool will be removed immediately from its creation time (unix timestamp).\n* In your CI machines when your run multiple tests on the same time,\nyou probably want to change cleanup `CONTAINER_STALE_MIN` to 20-30 minutes in order to prevent cleanup collision between tests.\n\nafter:\nCleanup of current running environment containers.\n\n* On local developer machine (NODE_ENV empty or equal to development) cleanup run immediately on each run.\nWhen in development mode you can control cleanup flow. Example:\n\n ```js\n // run only a and b, do not cleanup container (We need them up and running for second call to dockerComposeTool)\n const envName = dct.dockerComposeTool(before, after, pathToCompose, {startOnlyTheseServices: ['a', 'b'], containerCleanUp: false});\n\n// add services c and d with the same envName. Do not perform full cleanup on before.\n dct.dockerComposeTool(before, after, pathToCompose, {startOnlyTheseServices: ['c', 'd'], envName, cleanUp: false});\n // now run all the rest\n dct.dockerComposeTool(before, after, pathToCompose, {envName});\n ```\ncleanup parameters:\n`cleanUp` - true/false (default true) control on full cleanup on before function.\n`containerCleanUp` - true/false (default true) control on containers cleanup on after function.\n\n\n## Usage example\n\nAssume the following docker-compose.yml\n```yaml\nservice1:\n    image: ubuntu:14.04\n    links:\n        - db\n    ports:\n        - '3002'\n\nservice2:\n    image: ubuntu:14.04\n    links:\n        - db\n    ports:\n        - '3004'\n\ndb:\n    image: mongo:3.3\n    ports:\n        - '27017'\n\n```\n\nAfter using our package's code to fire up an environment as defined in the Yaml file you will have 3 services up and running\nin your computer as Docker containers. all of them attaching a random TCP/IP port to your host computer (IP 127.0.0.1 / 0.0.0.0)\n\nConsider the following Javascript code which is supposed to be placed in your end to end test suite setup.js file\n(most preferably in your before() block)\n\n```js\n\nconst {before, after} = require('mocha');\nconst {dockerComposeTool} = require('docker-compose-mocha');\nconst pathToCompose = './docker-compose.yml';\n\nconst envName = dockerComposeTool(before, after, pathToCompose);\n\n```\n\nOnce this code ran before your test suite, you will have all the services from your Yaml file\nup and running and ready to receive requests from your application under test.\n\nSince these services are fired up under random TCP/IP ports you will need a way to know which\nservice is available at which address. For that we have supplied an helper function which can do just that\n\nPlease consider the following code\n\n```js\n\nconst {before, after} = require('mocha');\nconst {dockerComposeTool, getAddressForService} = require('docker-compose-mocha');\nconst pathToCompose = './docker-compose.yml';\n\nconst envName = dockerComposeTool(before, after, pathToCompose);\n\nconst serviceName = 'service1';\nconst originalPort = 3002;\n\ngetAddressForService(envName, pathToCompose, serviceName, originalPort)\n    .then((result) =\u003e {\n        console.log(result); // =\u003e '0.0.0.0:36589'\n    });\n\n```\n\nThis way you can find out on which address every service form your Docker Compose is running\n\n## Running Sub-environments\n\nIn some cases, you would like to run a subset of the services in the docker-compose file, and maybe run the rest after\nthat. For these cases, the last `option` parameter is used. It comprises the following two _optional_ fields:\n\n* `startOnlyTheseServices`: an array of strings, comprising the services we want to run. If this value is undefined,\nthe default is to run all services.\n* `envName`: if you already ran a subset of the services, and want to run another subset _under the same environment_,\nspecify here the envName you received in the previous call.\n* `cleanUp`: specify here if you want to run full cleanup (run on mocha before).\n* `containerCleanUp`: specify here if you want to run container cleanup (run on mocha after).\n\nDisabling cleanup is especially useful when you run sub environments.\n\nExample:\n\n```js\n// run only a and b\nconst envName = dct.dockerComposeTool(before, after, pathToCompose, {startOnlyTheseServices: ['a', 'b'], containerCleanUp: false});\n// add services c and d\ndct.dockerComposeTool(before, after, pathToCompose, {startOnlyTheseServices: ['c', 'd'], envName, cleanUp: false});\n// now run all the rest\ndct.dockerComposeTool(before, after, pathToCompose, {envName});\n```\n\nYou can also perform starting and stoping dockerized services during the test:\n\n1. stop the service (containers) which was started inside the docker compose file\nconst serviceName = 'dct_s1';\nconst envName = main.dockerComposeTool(before, after, pathToCompose, {envName});\nyield dockerStopByServiceName(generatedEnvName, pathToCompose, serviceName);\n\n2. and then you can start the service (container) after it was stopped\nconst afterStopResults = yield dockerListByServiceName(generatedEnvName, pathToCompose, serviceName);\nexpect(afterStopResults).to.eql(false);\nyield dockerStartByServiceName(generatedEnvName, pathToCompose, serviceName);\n\n3. check if a service is running by serviceName and status Up\nconst afterStopResults = yield dockerListByServiceName(generatedEnvName, pathToCompose, serviceName);\n\n```js\n// run only a and b\nconst envName = dct.dockerComposeTool(before, after, pathToCompose, {startOnlyTheseServices: ['a', 'b']});\n// add services c and d\ndct.dockerComposeTool(before, after, pathToCompose, {startOnlyTheseServices: ['c', 'd'], envName});\n// now run all the rest\ndct.dockerComposeTool(before, after, pathToCompose, {envName});\n```\n\n## Optimization options\n\n* `brutallyKill`: will destroy the containers and not gently stop them. Usually, for test containers\n  this is enough and improves shutdown considerably.\n* `shouldPullImages`: will pull images only if this is true (and the default is true), otherwise it will\n  assume they are already pulled. This should be used only in production, and thus should be used thusly:\n  `shouldPullImages: !!process.env.NODE_ENV \u0026\u0026 process.env.NODE_ENV !== 'production'`\n\n## Service checking\n\nSince version `1.0.7` support for service checking was added with built in support for HTTP services\nfor all Natural Intelligence services (counting on the service to have a /healthcheck route)\n\nNotice in the last example we have a `healthCheck` property inside the `options` object which\nhas two properties. Once the entire `healthCheck` object is supplied and state set to `true`\nthe Docker Compose Mocha will automatically scan all services available under your Compose yaml file\nand will service check their availability using a simple HTTP GET health checker under the route\nof `http://0.0.0.0:XXXX/healthcheck` - `XXXX` being the random port of your service.\n\nHere's an example code of the service checking ability:\n\n```js\n\nconst {before, after} = require('mocha');\nconst {dockerComposeTool} = require('docker-compose-mocha');\nconst pathToCompose = './docker-compose.yml';\nconst options = {\n    healthCheck: {\n        state: true,\n        options: {\n            custom: {\n                mysql: Promise.coroutine(function*(address) {\n                    // =\u003e Do some code here to check when\n                    // mysql is ready to accept connections\n                })\n             }\n        }\n    }\n};\n\nconst envName = dockerComposeTool(before, after, pathToCompose);\n\n```\n\n### Custom polling methods\n\nIn case you want to add a custom polling method you can do so easily as can be seen in the example.\nYour polling method will accept as an argument the address at which your service can be found. If for example\nour service is a MySQL container tagged in your compose file as the service `mysql` listening on the port `3306`\nand binded to your host at port `30156`. Your polling method will accept `0.0.0.0:30156` (string) as an input\ninto your method so you can do your polling mechanism. Example of such a method can look like the following:\n\n(Important: your method should be thenable (returns a promise, and can also be (more advisable) a coroutine\nand should also return `true` upon a successful polling or `false` for a non successful one)\n\n```js\nconst options = {\n  custom: {\n    mysql: Promise.coroutine(function*(address) {\n        try {\n          const connection = yield mysqlDriver.connect(address);\n          console.log(connection); // =\u003e The connection here should be open\n          return true;\n        } catch (err) {\n          return false;\n        }\n    })\n  }\n}\n```\n\n## Credits and Thank you's\n\nThanks for reading and enjoy Dockerizing your end to end test suites.\n\nThis package was developed by: [Itamar Arjuan](https://github.com/itamararjuan) and with some help from:\n[Gil Tayar](https://github.com/giltayar) and [Rotem Bloom](https://github.com/rockrotem).\n\nNatural Intelligence - Node Infrastructure Team\nHere at Natural Intelligence we use this tool to setup our end to end test suites\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatural-intelligence%2Fdocker-compose-mocha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnatural-intelligence%2Fdocker-compose-mocha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatural-intelligence%2Fdocker-compose-mocha/lists"}