{"id":20845766,"url":"https://github.com/urbanos-public/divo","last_synced_at":"2025-12-12T00:30:32.415Z","repository":{"id":41812695,"uuid":"172127483","full_name":"UrbanOS-Public/divo","owner":"UrbanOS-Public","description":"Docker Integration and Validation Orchestrator for Elixir with Mix","archived":false,"fork":false,"pushed_at":"2023-05-25T21:08:58.000Z","size":139,"stargazers_count":35,"open_issues_count":2,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-08-05T03:36:32.222Z","etag":null,"topics":["docker","elixir","testing-tools"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/divo/readme.html","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UrbanOS-Public.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}},"created_at":"2019-02-22T20:03:01.000Z","updated_at":"2025-05-06T14:15:53.000Z","dependencies_parsed_at":"2023-07-13T08:28:13.595Z","dependency_job_id":null,"html_url":"https://github.com/UrbanOS-Public/divo","commit_stats":null,"previous_names":["smartcitiesdata/divo"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/UrbanOS-Public/divo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UrbanOS-Public%2Fdivo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UrbanOS-Public%2Fdivo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UrbanOS-Public%2Fdivo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UrbanOS-Public%2Fdivo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UrbanOS-Public","download_url":"https://codeload.github.com/UrbanOS-Public/divo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UrbanOS-Public%2Fdivo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270364971,"owners_count":24571423,"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-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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":["docker","elixir","testing-tools"],"created_at":"2024-11-18T02:13:53.335Z","updated_at":"2025-12-12T00:30:32.383Z","avatar_url":"https://github.com/UrbanOS-Public.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Hex.pm Version](http://img.shields.io/hexpm/v/divo.svg?style=flat)](https://hex.pm/packages/divo)\n\n# Getting Started\n\nEasily run Elixir integration tests with docker-compose.\nProvide Divo with docker-compose configuration, add `use Divo` to your integration tests, and run with `mix test.integration`.\n\n## Installation\n\nThe package can be installed by adding `divo` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps() do\n  [\n    {:divo, \"~\u003e 2.0.0\", only: [:dev, :integration]}\n  ]\nend\n```\n\nThe docs can be found at [https://hexdocs.pm/divo](https://hexdocs.pm/divo).\nNew versions are published with actions upon github release.\n\n## Configuration\n\n### Docker\nDefine services in your mix configuration file to define the dockerized service(s) you want to run as a dependency of your Elixir app.\nDefine divo config in one of the following three ways:\n\n#### Method 1 - Compose file\nIn your config, include the path to the yaml or json-formatted compose file\n```elixir\n#config/config.exs\nconfig :myapp,\n  divo: \"test/support/docker-compose.yaml,\n  divo_wait: [dwell: 700, max_tries: 50]\n```\n\n```yaml\n#test/support/docker-compose.yaml\nversion: '3'\nservices:\n  redis:\n    image: redis\n    ports:\n      - \"6379:6379\"\n    healthcheck:\n      test: [\"CMD\", \"redis-cli\", \"PING\"]\n      interval: 5s\n      timeout: 10s\n      retries: 3\n```\n\n#### Method 2 - Pre-existing module\nIn your mix file, include the additional dependency\n```elixir\n#mix.exs\ndef deps() do\n  [\n    {:divo, \"~\u003e 2.0.0\", only: [:dev, :integration]},\n    {:divo_redis, \"~\u003e 1.0.0\", only: [:dev, :integration]}\n  ]\n```\nAnd in your config, include the imported dependency module(s) as a list of tuples along with any environment variables the stack takes as a keyword list\n```elixir\n#config/config.exs\nconfig :myapp,\n  divo: [\n    {DivoRedis, [initial_key: \"myapp:secret\"]}\n  ],\n  divo_wait: [dwell: 700, max_tries: 50]\n```\n\n##### Known Modules:\n- [Kafka](https://github.com/smartcitiesdata/divo_kafka)\n- [Redis](https://github.com/smartcitiesdata/divo_redis)\n- [Machinebox](https://github.com/joshrotenberg/divo_machinebox)\n\n#### Method 3 - Elixir map\n```elixir\n#config/config.exs\nconfig :myapp,\n  divo: %{\n    version: \"3\",\n    services: %{\n      redis: %{\n        image: \"redis:latest\",\n        ports: [\n          \"6379:6379\"\n        ],\n        healthcheck: %{\n          test: [\"CMD\", \"redis-cli\", \"PING\"],\n          interval: \"5s\",\n          timeout: \"10s\",\n          retries: 3\n        }\n      }\n    }\n  },\n  divo_wait: [dwell: 700, max_tries: 50]\n```\n\n### Split Unit and Integration Tests\nYou will need to move any existing unit tests into a sub directory.  We recommend the following structure:\n```\nmyapp\n  └── test\n      ├── integration\n      │   ├── myapp_test.exs\n      │   └── test_helper.exs\n      └── unit\n          ├── module_a_test.exs\n          ├── module_b_test.exs\n          └── test_helper.exs\n```\nNOTE: `test_helper.exs` must be included in the root of both integration and unit tests.\n\n### Test Paths\nAdd this to your mix.exs to ensure that your unit and integration tests run in isolation from each other.\n```elixir\n#mix.exs\n\ndef project do\n  [\n    # ...\n    test_paths: test_paths(Mix.env())\n  ]\nend\n\n# ...\n\ndefp test_paths(:integration), do: [\"test/integration\"]\ndefp test_paths(_), do: [\"test/unit\"]\n```\n\n### Use Divo in an Integration Test\n\nIn each integration module add:\n\n`use Divo`\n\nDivo will then take care of running `docker-compose up` before running your tests\nand then run `docker-compose down` after they've completed.\n\nNOTE: Divo will start and stop docker-compose for every integration test module, unless the \"DIVO_DOWN\" environment variable is set to \"DISABLED\".\n\nExample Integration Test Module using [redix](https://hex.pm/packages/redix):\n```elixir\ndefmodule MyAppTest do\n  use ExUnit.Case\n  use Divo\n\n  test \"persisting and reading from redis\" do\n    {:ok, conn} = Redix.start_link(host: \"localhost\", port: 6379)\n    Redix.command(conn, [\"SET\", \"mykey\", \"foo\"])\n    {:ok, result} = Redix.command(conn, [\"GET\", \"mykey\"])\n    assert result === \"foo\"\n  end\nend\n```\n\n## Use Divo for the entire test suite\nIn your integration or test suite's `test_helper.exs` file add `Divo.Suite.start()` before `ExUnit.start()`\nExample:\n```elixir\nDivo.Suite.start()\n...\nExUnit.start()\n```\n\nThis will make Divo stand up dockers that last the entire run of the test suite (or just a few modules or tests if you specified them in your `mix test.integration` command). It will wire itself up to tear down the dockers if in cases where the tests fail to compile.\n\nIdeally, you will want to NOT have `use Divo` in your tests. However, if you leave `use Divo` in for all of the tests, and still add the start to your `test_helper.exs` the tests will still run as expected, with an additional docker start and stop wrapped around the whole run.\n\nThe `Divo.Suite.start` function takes all of the options that `use Divo` does plus a few extras for controlling where the final docker cleanup occurs:\n- `auto_cleanup?` - whether or not to cleanup dockers on program exit. Defaults to `true`\n\nWhether or not you choose to let it cleanup after itself, `Divo.Suite.start` will return a zero-arity cleanup hook that you can call when you want to explicitly cleanup the dockers.\n```elixir\nDivo.Suite.start()\n|\u003e on_exit()\n```\n\n## Running Integration Tests\n\nIntegration tests are executed by running:\n\n`mix test.integration`\n\n## License\nReleased under [Apache 2 license](https://github.com/smartcitiesdata/divo/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbanos-public%2Fdivo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furbanos-public%2Fdivo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbanos-public%2Fdivo/lists"}