{"id":17111115,"url":"https://github.com/davidrjonas/blackbox","last_synced_at":"2025-10-14T20:33:31.320Z","repository":{"id":75475145,"uuid":"173871688","full_name":"davidrjonas/blackbox","owner":"davidrjonas","description":"A simple yaml-driven http testing tool.","archived":false,"fork":false,"pushed_at":"2019-03-05T08:31:02.000Z","size":28,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-23T22:20:02.325Z","etag":null,"topics":["api","blackbox","http","rest","testing"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/davidrjonas.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-05T04:12:50.000Z","updated_at":"2021-10-21T18:04:49.000Z","dependencies_parsed_at":"2023-06-06T14:45:21.139Z","dependency_job_id":null,"html_url":"https://github.com/davidrjonas/blackbox","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/davidrjonas/blackbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidrjonas%2Fblackbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidrjonas%2Fblackbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidrjonas%2Fblackbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidrjonas%2Fblackbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidrjonas","download_url":"https://codeload.github.com/davidrjonas/blackbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidrjonas%2Fblackbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279020904,"owners_count":26086948,"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-10-14T02:00:06.444Z","response_time":60,"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":["api","blackbox","http","rest","testing"],"created_at":"2024-10-14T16:49:15.420Z","updated_at":"2025-10-14T20:33:31.295Z","avatar_url":"https://github.com/davidrjonas.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"blackbox\n========\n\nBlackbox is a simple yaml-driven http testing tool built on go's included testing tools.\n\n- Define tests in YAML.\n- YAML can use [go templates](https://golang.org/pkg/text/template/) with [Sprig functions](http://masterminds.github.io/sprig/)\n- .env support\n\nUsage\n-----\n\nBy default, `blackbox` looks for files named `test*.yaml` in the current directory. You may specify as many files you like. You may also read from stdin, `cat test_example.yaml | blackbox -- -`.\n\n```bash\nUsage of ./blackbox [files...]\n  # ... lots of `go test` flags elided. Just the useful ones for us included here.\n  -test.failfast\n        do not start new tests after the first test failure\n  -test.run regexp\n        run only tests and examples matching regexp\n  -test.v\n        verbose: print additional output\n  -wait-extra int\n        Seconds to wait regardless of -wait-for-url status [env: BLACKBOX_WAIT_EXTRA]\n  -wait-for-url string\n        Wait for this url to become available (status 200) [env: BLACKBOX_WAIT_FOR_URL]\n```\n\nRun only select tests\n\n```bash\nblackbox -test.v -test.run '.*/Test_POST_json'\n```\n\nA heavily annotated example of all the options. Also see the [test_example.yaml](test_example.yaml).\n\n```yaml\n# The top level object is an array. You may have many tests or just one.\n- name: Test 1\n\n  # The URL to test. You can use env vars easily.\n  url: http://httpbin.org/get?home={{env \"HOME\" | urlencode }}\n\n  # Defafults to GET unless data is set, then POST\n  method: GET\n\n  # Setting data automatically makes the request a POST and sets the\n  # content-type to application/x-www-form-urlencoded if it is not already set.\n  # If you want json, for now you need to set the header.\n  data:\n    content: example=test\n\n  # Add headers\n  headers:\n    host: publicname.example.org\n    authorization: Bearer ABC123\n\n  # Add basic auth\n  basicAuth: [\"username\", \"password\"]\n\n  # If the the response is a 3xx, follow to the new Location. By default this\n  # is false and probably what you want for testing.\n  followRedirects: true\n\n  # And now some expectations for the response.\n  expect:\n    # Check the HTTP status code\n    status: 200\n\n    # Check the body. All specified must match!\n    body:\n      # Match this string exactly. New lines and whitespace too.\n      content: \"Hello, World!\"\n\n      # Since \"content: ''\" would appear the same as if you didn't specify the\n      # \"content\" key, set \"empty\" to true to expect an empty body.\n      empty: true\n\n      # Match a regular expression. See https://github.com/google/re2/wiki/Syntax\n      regex: '^Hello'\n\n    # Header values must match exactly\n    headers:\n      content-type: text/plain\n\n    # Okay, this is cool. Use another request as a prototype against which to\n    # compare. When testing the new version of an API you can compare against the\n    # old version.\n    fromRequest:\n      # All the same options as the top level request\n      url: http://httpbin.org/get\n\n      # There is one that isn't at the top level, headerWhitelist. These are\n      # the headers that will be compared. We can't compare all headers because\n      # many change per request, such as Date:\n      headerWhitelist:\n        - content-type\n```\n\nAdditional Template Functions\n-----------------------------\n\n### urlencode\n\nEncode strings to be used safely as part of a url.\n\n```\n# Will evaluate to \"this%2Fthat\"\n{{ this/that | urlencode }}\n```\n\nDocker-compose Example\n----------------------\n\n```\nversion: \"3.4\"\n\nservices:\n  httpbin:\n    image: mccutchen/go-httpbin\n\n  blackbox:\n    image: davidrjonas/blackbox\n    environment:\n      # In your tests use HOST like `url: http://{{env \"HOST\"}}/get`\n      - HOST=httpbin:8080\n      - BLACKBOX_WAIT_FOR_URL=http://httpbin:8080/get\n      - BLACKBOX_WAIT_EXTRA=2\n    volumes:\n      - ./:/tests\n```\n\nNow run your tests in that environment. `--abort-on-container-exit` will make the containers shut down when `blackbox` exits.\n\n```bash\ndocker-compose up --abort-on-container-exit\n```\n\nBuild From Source\n-----------------\n\nThe build is a little odd since we want to run `TestMain()` and use the built-in test framework which is normally stripped from a binary. Luckily, `go test` has an escape hatch for building a test binary.\n\nRegardless, [Makefile](Makefile) has everything you need.\n\n```bash\nmake blackbox\n```\n\nCross-compile with the usual `GOOS` and `GOARCH`\n\n```bash\nGOOS=linux GOARCH=arm64 make blackbox\n# outputs blackbox-linux-arm64\n```\n\nFuture Features\n---------------\n\n- [X] JSON Schema matching (expect.body.jsonSchema)\n- [X] Use another request response as a template to match (expect.fromRequest)\n- [ ] Simple JSON data matchers\n- [ ] Validate JSON Schema earlier\n\nSimilar Projects\n----------------\n\n- [pyresttest](https://github.com/svanoort/pyresttest)\n- [tavern](https://github.com/taverntesting/tavern)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidrjonas%2Fblackbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidrjonas%2Fblackbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidrjonas%2Fblackbox/lists"}