{"id":22848350,"url":"https://github.com/feedzai/cosy-test","last_synced_at":"2025-06-25T10:32:08.317Z","repository":{"id":48373969,"uuid":"109962776","full_name":"feedzai/cosy-test","owner":"feedzai","description":"Bringing up Docker Compose environments for system, integration and performance testing, with support for ScalaTest and Gatling","archived":false,"fork":false,"pushed_at":"2021-07-29T10:04:06.000Z","size":71,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-30T04:48:57.538Z","etag":null,"topics":["docker","docker-compose","gatling","integration-testing","scalatest","system-testing"],"latest_commit_sha":null,"homepage":"","language":"Scala","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/feedzai.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-11-08T10:42:57.000Z","updated_at":"2021-10-28T10:01:50.000Z","dependencies_parsed_at":"2022-08-26T09:41:56.227Z","dependency_job_id":null,"html_url":"https://github.com/feedzai/cosy-test","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feedzai%2Fcosy-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feedzai%2Fcosy-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feedzai%2Fcosy-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/feedzai%2Fcosy-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/feedzai","download_url":"https://codeload.github.com/feedzai/cosy-test/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251644827,"owners_count":21620630,"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":["docker","docker-compose","gatling","integration-testing","scalatest","system-testing"],"created_at":"2024-12-13T04:11:29.463Z","updated_at":"2025-04-30T04:49:05.533Z","avatar_url":"https://github.com/feedzai.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cosy-test\n[![Build Status](https://travis-ci.org/feedzai/cosy-test.svg?branch=master)](https://travis-ci.org/feedzai/cosy-test)\n[![codecov](https://codecov.io/gh/feedzai/cosy-test/branch/master/graph/badge.svg)](https://codecov.io/gh/feedzai/cosy-test)\n[![Maven metadata URI](https://img.shields.io/maven-metadata/v/http/central.maven.org/maven2/com/feedzai/cosy-test_2.12/maven-metadata.xml.svg)](https://mvnrepository.com/artifact/com.feedzai/cosy-test)\n\nBringing up Docker Compose environments for system, integration and performance testing, with support for [ScalaTest](http://www.scalatest.org/),\n[JUnit 4](https://junit.org/junit4/), [JUnit 5](https://junit.org/junit5/), [TestNG](http://testng.org/doc/)  and [Gatling](https://gatling.io/).\n\n## Why do I need this?\n\nImagine you need to test a complex system that requires having a lot of components working and simulating a realistic scenario.\nProbably, you would just use a docker-compose file to start your environment and then do your tests.\nThat seems easy... But:\n\n* How would you know that the environment is already up and running for testing?\n* What if you need to test a lot of those environments concurrently?\n* Would you be capable of managing all the container mapped ports without conflicts?\n\nThat is where `cosy-test` can make your life easier.\n\n## What is cosy-test and how it helps you?\n\nIt is a simple framework that allows integration with several testing frameworks.\nWith `cosy-test` it is possible to simply use docker compose files and define environment variables in order to\nstart docker environments, run tests and bring environments down without pains and restrictions.\n\nMain features:\n\n* Brings the environments up before the tests and tears them down afterwards.\n* Start tests just after all health checks are passing.\n* Can be configured to dump container logs for debugging purposes.\n* Containers can be kept running on failure, success or both.\n* Control your system through environment variables.\n* Ports exposed by containers are mapped to the host machine and are made available to the tests. This approach is\n  especially handy on MacOS (as opposed to reaching the containers by their IP addresses).\n\n## Requirements\n\nIn order for `cosy-test` to work, it is necessary to have Docker and Docker Compose installed. There are no version restrictions,\nhowever we recommend using:\n\n- Docker \u003e= 18.02.0 (_older versions have problems during containers start up and/or tear down_)\n- Docker Compose \u003e= 1.17.1\n\n## Usage\n\nSBT\n\n    libraryDependencies += \"com.feedzai\" %% \"cosy-test\" % \"0.0.3\"\n\nMaven\n\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.feedzai\u003c/groupId\u003e\n        \u003cartifactId\u003ecosy-test_2.12\u003c/artifactId\u003e\n        \u003cversion\u003e0.0.3\u003c/version\u003e\n    \u003c/dependency\u003e\n\n## Example — ScalaTest\n\n``` scala\nclass IntegrationSpec extends FlatSpec with DockerComposeTestSuite with MustMatchers {\n\n  def dockerSetup = Some(\n    DockerComposeSetup(\n      \"scalatest\",  // Setup name\n      Seq(Paths.get(\"src\", \"test\", \"resources\", \"docker-compose-scalatest.yml\")), // Docker compose files\n      Paths.get(\"\").toAbsolutePath, // Docker compose working directory\n      Map.empty // Environment variables. Example: Map(\"CONTAINER_EXPOSED_PORT\" -\u003e \"80\")\n    )\n  )\n\n  behavior of \"Scala Test\"\n\n  it must \"Retrieve all services\" in {\n    val expectedServices = Set(\"container1\", \"container2\", \"container3\")\n    dockerSetup.foreach { setup =\u003e\n      setup.getServices().toSet mustEqual expectedServices\n    }\n  }\n}\n```\n\n\n## Example — JUnit 4\n\n``` java\npublic class IntegrationSpec {\n\n    private static final DockerComposeJavaSetup dockerSetup;\n\n    static {\n        dockerSetup = new DockerComposeJavaSetup(\n            \"junit4test\", // Setup name\n            Collections.singletonList(Paths.get(\"src\", \"test\", \"resources\", \"docker-compose-junit4.yml\")), // Docker compose files\n            Paths.get(\"\").toAbsolutePath(), // Docker compose working directory\n            new HashMap\u003c\u003e() // Environment variables. Example: envMap.put(\"CONTAINER_EXPOSED_PORT\", \"80\")\n        );\n    }\n\n    @ClassRule\n    public static DockerComposeRule dockerComposeRule = new DockerComposeRule(SetupManager.builder(dockerSetup).build());\n\n    @Rule\n    public TestWatcher testWatcher = new TestWatcher() {\n        @Override\n        protected void failed(Throwable e, Description description) {\n            dockerComposeRule.setTestFailed(true);\n        }\n    };\n\n    @Test\n    public void fetchServices() {\n       Assert.assertThat(\n           dockerSetup.getServices(),\n           containsInAnyOrder(\"container1\", \"container2\", \"container3\")\n       );\n    }\n}\n```\n\n## Example — JUnit 5\n\n``` java\npublic class IntegrationSpec {\n\n    private static final DockerComposeJavaSetup dockerSetup;\n\n    static {\n        dockerSetup = new DockerComposeJavaSetup(\n            \"junit5test\", // Setup name\n            Collections.singletonList(Paths.get(\"src\", \"test\", \"resources\", \"docker-compose-junit5.yml\")), // Docker compose files\n            Paths.get(\"\").toAbsolutePath(),  // Docker compose working directory\n            new HashMap\u003c\u003e() // Environment variables. Example: envMap.put(\"CONTAINER_EXPOSED_PORT\", \"80\")\n        );\n    }\n\n    @RegisterExtension\n    static DockerComposeExtension extension = new DockerComposeExtension(SetupManager.builder(dockerSetup).build());\n\n    @Test\n    public void fetchServices() {\n        Assert.assertThat(\n            dockerSetup.getServices(),\n            containsInAnyOrder(\"container1\", \"container2\", \"container3\")\n        );\n    }\n}\n```\n\n## Example — TestNG\n\n``` scala\npublic class IntegrationSpec extends DockerComposeAbstraction {\n\n    private final DockerComposeJavaSetup dockerSetup = new DockerComposeJavaSetup(\n        \"testngtest\", // Setup name\n        Collections.singletonList(Paths.get(\"src\", \"test\", \"resources\", \"docker-compose-testng.yml\")), // Docker compose files\n        Paths.get(\"\").toAbsolutePath(), // Docker compose working directory\n        new HashMap\u003c\u003e() // Environment variables. Example: envMap.put(\"CONTAINER_EXPOSED_PORT\", \"80\")\n    );\n\n    IntegrationSpec() {\n        setupManager = SetupManager.builder(dockerSetup).build();\n    }\n\n    @Test\n    public void fetchServices() {\n        Assert.assertThat(\n            dockerSetup.getServices(),\n            containsInAnyOrder(\"container1\", \"container2\", \"container3\")\n        );\n    }\n}\n```\n\n## Example — Gatling\n\n``` scala\nclass IntegrationSpec extends DockerComposeSimulation {\n\n  override def dockerSetup = Some(\n    DockerComposeSetup(\n      \"gatling\", // Setup name\n      Seq(Paths.get(\"src\", \"test\", \"resources\", \"docker-compose-gatling.yml\")), // Docker compose files\n      Paths.get(\"\").toAbsolutePath, // Docker compose working directory\n      Map.empty // Environment variables. Example: Map(\"CONTAINER_EXPOSED_PORT\" -\u003e \"80\")\n    )\n  )\n\n  beforeSimulation()\n\n  private val HttpProtocol: HttpProtocolBuilder = http\n    .baseURL(\"http://localhost:8086\")\n\n  private val populationBuilder = {\n    val getAction = http(\"Gatling simulation\").get(\"\")\n    val s = scenario(\"Gatling simulation\")\n    s.during(10.seconds)(feed(Iterator.empty).exec(getAction))\n      .inject(rampUsers(10).over(1.second))\n      .protocols(HttpProtocol)\n  }\n\n  setUp(populationBuilder)\n}\n```\n\n## Build, Test and Release\n\nAfter cloning the repository you can simply build and run the tests, by executing the command:\n\n    sbt test\n\nSince `cosy-test` uses [sbt-dynver](https://github.com/dwijnand/sbt-dynver) to release a new version it is just required\nto create a new tag like:\n\n    git tag v1.0.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeedzai%2Fcosy-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffeedzai%2Fcosy-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeedzai%2Fcosy-test/lists"}