{"id":23709459,"url":"https://github.com/robert-chiniquy/depends-on","last_synced_at":"2025-09-03T15:31:21.966Z","repository":{"id":13714491,"uuid":"16408508","full_name":"robert-chiniquy/depends-on","owner":"robert-chiniquy","description":"External process runner for nodejs tests","archived":false,"fork":false,"pushed_at":"2015-04-24T14:11:30.000Z","size":482,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2024-12-25T04:34:19.773Z","etag":null,"topics":["javascript","node","tape","testing"],"latest_commit_sha":null,"homepage":"https://www.npmjs.org/package/depends-on","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robert-chiniquy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-31T13:17:27.000Z","updated_at":"2016-09-23T20:59:27.000Z","dependencies_parsed_at":"2022-09-03T19:43:02.527Z","dependency_job_id":null,"html_url":"https://github.com/robert-chiniquy/depends-on","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robert-chiniquy%2Fdepends-on","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robert-chiniquy%2Fdepends-on/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robert-chiniquy%2Fdepends-on/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robert-chiniquy%2Fdepends-on/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robert-chiniquy","download_url":"https://codeload.github.com/robert-chiniquy/depends-on/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231898234,"owners_count":18442799,"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":["javascript","node","tape","testing"],"created_at":"2024-12-30T18:30:00.918Z","updated_at":"2024-12-30T18:30:01.605Z","avatar_url":"https://github.com/robert-chiniquy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"depends-on\n==========\n\nManages the external services that your tests depend on. Think of it as [async.auto](https://github.com/caolan/async#auto) with process control for integration tests.\n\n[![Build Status](https://travis-ci.org/robert-chiniquy/depends-on.svg?branch=master)](https://travis-ci.org/robert-chiniquy/depends-on)\n\n## examples\n\n`dependencies.json` is a file describing your dependencies. Keep it next to your tests.\n\n### … with one dependency\n\n`test-thing.js`:\n```javascript\nvar ready = require('depends-on')('redis');\nvar test = require('tape');\n\ntest('init dependencies for ' + __filename, ready);\n\ntest('test that uses redis', function(t) {\n  …\n});\n```\n\n`dependencies.json`:\n```json\n{\n  \"redis\": {\n    \"cmd\": [\"/usr/sbin/redis-server\"],\n    \"wait_for\": {\n      \"port\": 6379\n    }\n  }\n}\n```\n\n`ready()` is a function that takes a callback (or a tape test object). It will call that callback when your dependencies are ready. They'll be stopped automatically when your tests are done.\n\n### … with multiple dependencies\n\nDependencies can have dependencies. This is the typical use case, where multiple services must start before your tests can run.\n\nBuilding on the previous example, say you want to clear all values from (or load some fixtures into) Redis after it starts, but before your tests run.\n\n`test-other-thing.js`:\n```javascript\nvar ready = require('depends-on')('fresh \u0026 clean redis');\nvar test = require('tape');\n\ntest('start fresh redis', ready);\n\ntest('test that uses redis', function(t) {\n  …\n});\n```\n\n`dependencies.json`:\n```json\n{\n  \"redis-server\": {\n    \"cmd\": [\"/usr/sbin/redis-server\"],\n    \"wait_for\": {\n      \"port\": 6379\n    }\n  },\n  \"fresh \u0026 clean redis\": {\n    \"cmd\": [\"./bin/flushall.sh\"],\n    \"depends\": [\"redis-server\"],\n    \"wait_for\": {\n      \"exit_code\": 0\n    }\n  }\n}\n```\n\nIf multiple tests are `require()`'d and share dependencies, depends-on will share them across the test files, each dependency only being started once. When node exits, all dependencies will stopped (by default with `SIGTERM` but the signal is configurable).\n\n## dependencies.json\n`dependencies.json` is a file containing a json object mapping dependency names to objects that describe each dependency.\n\n### dependency fields\n\n\u003cdl\u003e\n\u003cdt\u003ecmd\u003c/dt\u003e\n\u003cdd\u003earray of command and args for child_process.spawn\u003c/dd\u003e\n\n\u003cdt\u003edepends\u003c/dt\u003e\n\u003cdd\u003earray of names of dependencies which this dependency depends on\u003c/dd\u003e\n\n\u003cdt\u003ecwd\u003c/dt\u003e\n\u003cdd\u003eThe cwd to pass to child_process.spawn\u003c/dd\u003e\n\n\u003cdt\u003ewait_for\u003c/dt\u003e\n\u003cdd\u003eobject specifying a timeout and either an exit code or ip \u0026 port to wait for socket availability before considering a dependency started\u003c/dd\u003e\n\n\u003cdt\u003esignal\u003c/dt\u003e\n\u003cdd\u003esignal to use to stop the dependency when your tests end (default: `SIGTERM` )\u003c/dd\u003e\n\n\u003cdt\u003estdout\u003c/dt\u003e\n\u003cdd\u003epath to log dependency's stdout to (default: your stdout). This can be relative to either the `cwd` value you specify or `__dirname` of `dependencies.json`.\u003c/dd\u003e\n\n\u003cdt\u003estderr\u003c/dt\u003e\n\u003cdd\u003epath to log dependency's stderr to (default: your stderr). This can be relative to either the `cwd` value you specify or `__dirname` of `dependencies.json`.\u003c/dd\u003e\n\n\u003cdt\u003etruncateStdio\u003c/dt\u003e\n\u003cdd\u003eboolean, if true files stdio is piped to will be truncated on use\u003c/dd\u003e\n\n\n\u003c/dl\u003e\n\n### wait_for fields\n\nYou can wait for either a socket to be accepting connections or for a process to exit, so one of `port` or `exit_code` is required to use `wait_for`.\n\n```json\n    \"wait_for\": {\n      \"host\": \"127.0.0.1\",\n      \"port\": 22181,\n      \"timeout\": 30\n    }\n```\n\nBy default, depends-on will throw an error if one of the processes it starts exits before your tests are done. Use an `exit_code` in your `wait_for` block if a process is expected to complete and exit prior to tests running (maybe you're loading a db schema).\n\n```json\n    \"wait_for\": {\n      \"exit_code\": 0,\n      \"timeout\": 120\n    }\n```\n\n\u003cdl\u003e\n\n\u003cdt\u003ehost\u003c/dt\u003e\n\u003cdd\u003edefault: localhost\u003c/dd\u003e\n\n\u003cdt\u003eport\u003c/dt\u003e\n\u003cdd\u003eif port is set, will wait for a TCP connection to be accepted on this port\u003c/dd\u003e\n\n\u003cdt\u003eexit_code\u003c/dt\u003e\n\u003cdd\u003eif exit_code is set, will wait for the process to exit with this code before proceeding\u003c/dd\u003e\n\n\u003cdt\u003etimeout\u003c/dt\u003e\n\u003cdd\u003eseconds to wait before considering a dependency to have failed starting up (default: 30)\u003c/dd\u003e\n\n\u003c/dl\u003e\n\n## graph dependencies\n\nJust for fun, `bin/graph-dependencies.js` can graph the dependencies in your project with graphviz.\n\nFor example, graphing [the dependencies in this repo's fixtures](https://github.com/robert-chiniquy/depends-on/blob/master/tests/dependencies.json):\n`dot -Tpng -odeps.png \u003c(./bin/graph-dependencies.js) \u0026\u0026 open deps.png` -\u003e\n\n\u003cimg src=\"./deps.png\" width=600 /\u003e\n\n## notes\n### using with tape\nBe sure to `require('depends-on')` before you `require('tape')`. Like this:\n\n```javascript\nvar ready = require('depends-on')('something');\nvar test = require('tape');\n```\n\nBoth depends-on and tape have `process.on('exit', …)` handlers, but tape calls `process.exit` in its `process.on('exit', …)` handler, so if tape's handler runs first, depends-on's handler will never run (and child processes won't be cleaned up). Handlers run in the order they are added, so depends-on must be required first.\n\n### why not\n#### … use a bash script or Makefile?\n\nI like to be able to run integration tests individually like `$ node tests.js` without running anything else or relying on some external service coincidentally being on.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobert-chiniquy%2Fdepends-on","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobert-chiniquy%2Fdepends-on","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobert-chiniquy%2Fdepends-on/lists"}