{"id":15649154,"url":"https://github.com/peter-evans/smoke-testing","last_synced_at":"2026-03-04T23:02:58.298Z","repository":{"id":55083688,"uuid":"175155467","full_name":"peter-evans/smoke-testing","owner":"peter-evans","description":"Smoke testing Docker containers with CircleCI","archived":false,"fork":false,"pushed_at":"2021-01-12T01:34:39.000Z","size":144,"stargazers_count":44,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-06T09:02:27.325Z","etag":null,"topics":["circleci","containers","docker","smoke-testing"],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","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/peter-evans.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":"2019-03-12T07:14:51.000Z","updated_at":"2025-05-14T13:21:19.000Z","dependencies_parsed_at":"2022-08-14T11:30:55.375Z","dependency_job_id":null,"html_url":"https://github.com/peter-evans/smoke-testing","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/peter-evans/smoke-testing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-evans%2Fsmoke-testing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-evans%2Fsmoke-testing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-evans%2Fsmoke-testing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-evans%2Fsmoke-testing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peter-evans","download_url":"https://codeload.github.com/peter-evans/smoke-testing/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-evans%2Fsmoke-testing/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30098105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T22:49:54.894Z","status":"ssl_error","status_checked_at":"2026-03-04T22:49:48.883Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["circleci","containers","docker","smoke-testing"],"created_at":"2024-10-03T12:28:23.565Z","updated_at":"2026-03-04T23:02:58.261Z","avatar_url":"https://github.com/peter-evans.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Smoke Testing Containers [\u003cimg align=\"right\" alt=\"The blog of Peter Evans: Smoke Testing Containers\" title=\"View blog post\" src=\"https://peterevans.dev/img/blog-published-badge.svg\"\u003e](https://peterevans.dev/posts/smoke-testing-containers/)\n[![CircleCI](https://circleci.com/gh/peter-evans/smoke-testing/tree/master.svg?style=svg)](https://circleci.com/gh/peter-evans/smoke-testing/tree/master)\n\nSmoke testing is a class of testing designed to determine if something is ready for more rigorous testing. The terminology appears to have [originated from plumbing](https://en.wikipedia.org/wiki/Smoke_testing_(mechanical)) where smoke is used to test for leaks in a closed system of pipes. It also seems to be widely used in electronics to refer to the practice of turning on a new piece of hardware for the first time and considering it a success if none of the components overheat and start to smoke.\n\nIn software engineering, smoke testing is used to reveal basic failures that can allow us to immediately reject a software build. It is also sometimes called _\"Build Verification Testing,\" \"Confidence Testing,”_ or _\"Sanity Testing.\"_ The tests are usually a fast, simple check of major functionality to confirm that a build is ready to be subject to further testing. It can prevent flawed artifacts being released into QA environments, wasting both time and resources.\n\nWith smoke tests we can address basic questions, such as...\n\n- Does my component/service run?\n- Are interfaces accessible?\n- Do the main features appear to work?\n\n## But I already have unit tests!\n\nUnit tests and other types of testing that run before the final artifact is produced will not catch problems with packaging.\nSmoke tests are executed against the final artifact that will be published and/or deployed to a QA environment.\nIn some cases the artifact will just be a compiled binary and there might be very little that can go wrong.\nContainers, however, are a minefield of dependencies and security updates and it can be difficult to have a high degree of confidence about your final container image without testing it!\nOf course we can test it locally, but it should be automated in any good CI/CD pipeline.\nWe should be able to update our `Dockerfile` and `git push` knowing that if we have broken something obvious it will be caught.\nThis is where smoke tests can save us from causing a serious fire!\n\n## Smoke testing Docker containers with CircleCI\n\nThere are various ways to smoke test containers but I will outline a couple of techniques using [CircleCI](https://circleci.com/).\nCircleCI is probably the trickiest I've experienced due to the way they isolate the job container from the Docker build when using the `docker` executor type.\nThere is an option to avoid this by using the [`machine` executor type](https://circleci.com/docs/2.0/executor-types/#using-machine) that runs jobs in a dedicated, ephemeral VM.\nHowever, they warn that this method may incur additional fees in a future pricing update.\nSo the following techniques assume use of the `docker` executor type.\n\n### Networking containers\n\nTo [run Docker commands](https://circleci.com/docs/2.0/building-docker-images/) you must specify the `setup_remote_docker` key to create a remote Docker environment.\nThis is completely isolated from your job container so if, for example, you attempt to curl a running Docker container you will find it has no connectivity.\n\n```bash\ncurl: (7) Failed to connect to localhost port 8080: Connection refused\n```\n\nTo run our smoke tests, in whatever form they take, we need to package them in a container of their own and network them to the container we want to test.\nHere are two examples using publicly available Docker images to verify our service is running and returning a response from the `/healthcheck` endpoint.\n\nAn example using the Docker image [appropriate/curl](https://hub.docker.com/r/appropriate/curl/) to execute a `curl` request.\n```yaml\n- run:\n    name: Start the service and perform healthcheck\n    command: |\n      docker run -d --name my-service my-service\n      docker run --network container:my-service appropriate/curl --retry 10 --retry-connrefused http://localhost:8080/healthcheck\n```\n\nAn similar example using the Docker image [jwilder/dockerize](https://hub.docker.com/r/jwilder/dockerize/) to wait for a response from the healthcheck endpoint.\n```yaml\n- run:\n    name: Start the service and perform healthcheck\n    command: |\n      docker run -d --name my-service my-service\n      docker run --network container:my-service jwilder/dockerize -wait http://localhost:8080/healthcheck -timeout 120s -wait-retry-interval 5s\n```\n\n### Custom smoke tests\n\nUsing `curl` or [dockerize](https://github.com/jwilder/dockerize) to simply check for a `200 OK` response will most likely not be enough to adequately smoke test our container.\nThose tools do, however, perform a necessary role of making sure that the service is up and running before we execute further tests.\n\nSmoke tests can take whatever form you like provided they are executable via a container.\nThe following example demonstrates executing a [Postman](https://www.getpostman.com/) collection of smoke tests with the [postman/newman](https://hub.docker.com/r/postman/newman) Docker image.\nNote that in order to make our test files (in this case a JSON Postman collection) available to the test executor we create a separate container to store them.\nThis container defines a volume at the path we want our test files to be accessible in the executor container.\nThat volume is then mounted in the executor container using the `--volumes-from` flag to make the test files available at runtime.\n\n```yaml\n- run:\n    name: Execute smoke tests\n    command: |\n      docker run -d --name my-service my-service\n      # Create a container called \"smoke-tests\" to store our smoke test files\n      docker create -v /etc/newman --name smoke-tests alpine:3.4 /bin/true\n      # Copy test files from local directory 'smoke-tests' to the container\n      docker cp smoke-tests/. smoke-tests:/etc/newman\n      # Wait for service to be up and running\n      docker run --network container:my-service jwilder/dockerize -wait http://localhost:8080/healthcheck -timeout 120s -wait-retry-interval 5s\n      # Run smoke tests\n      docker run --network container:my-service --volumes-from smoke-tests -t postman/newman:4.4.0-alpine run my-service.postman_collection.json\n```\n\nSee the code in this repository for a complete example of these techniques.\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-evans%2Fsmoke-testing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeter-evans%2Fsmoke-testing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-evans%2Fsmoke-testing/lists"}