{"id":15152908,"url":"https://github.com/ipfs/gateway-conformance","last_synced_at":"2026-03-11T01:09:17.869Z","repository":{"id":65784426,"uuid":"598060199","full_name":"ipfs/gateway-conformance","owner":"ipfs","description":"a vendor-agnostic gateway conformance test suite for implementers of IPFS Gateways to ensure compliance with  https://specs.ipfs.tech/http-gateways/","archived":false,"fork":false,"pushed_at":"2026-02-28T22:02:40.000Z","size":5839,"stargazers_count":18,"open_issues_count":65,"forks_count":15,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-03-10T17:45:45.024Z","etag":null,"topics":["ipfs","ipfs-api","ipfs-gateway","ipfs-http-client"],"latest_commit_sha":null,"homepage":"https://specs.ipfs.tech/http-gateways/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipfs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-06T10:07:23.000Z","updated_at":"2026-02-24T17:02:54.000Z","dependencies_parsed_at":"2023-11-06T23:06:09.103Z","dependency_job_id":"85fe38b5-cb92-411b-9d1d-2db7568571a3","html_url":"https://github.com/ipfs/gateway-conformance","commit_stats":{"total_commits":546,"total_committers":15,"mean_commits":36.4,"dds":0.3076923076923077,"last_synced_commit":"7e38044072e5c3e08690ebb58f21444815f43f22"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/ipfs/gateway-conformance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fgateway-conformance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fgateway-conformance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fgateway-conformance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fgateway-conformance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs","download_url":"https://codeload.github.com/ipfs/gateway-conformance/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fgateway-conformance/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30364989,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"ssl_error","status_checked_at":"2026-03-10T21:40:59.357Z","response_time":106,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["ipfs","ipfs-api","ipfs-gateway","ipfs-http-client"],"created_at":"2024-09-26T16:41:34.782Z","updated_at":"2026-03-11T01:09:17.854Z","avatar_url":"https://github.com/ipfs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003ca href=\"#readme\"\u003e\u003cimg src=\"https://github.com/ipfs/gateway-conformance/assets/157609/4e7ba998-c7f7-415b-bd72-eef053474865\" alt=\"Boxo logo\" title=\"Boxo logo\" width=\"300\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n  Gateway Conformance\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\" style=\"font-size: 1.2rem;\"\u003eA set of GO and HTTP tools for testing implementation compliance with https://specs.ipfs.tech\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ipfs.tech\"\u003e\u003cimg src=\"https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square\" alt=\"Official Part of IPFS Project\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://specs.ipfs.tech\"\u003e\u003cimg src=\"https://img.shields.io/badge/specs-IPFS-blue.svg?style=flat-square\" alt=\"IPFS Specifications\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ipfs/boxo/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ipfs/boxo/go-test.yml?branch=main\" alt=\"ci\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ipfs/gateway-conformance/releases\"\u003e\u003cimg alt=\"GitHub release\" src=\"https://img.shields.io/github/v/release/ipfs/gateway-conformance?filter=!*rc*\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003chr /\u003e\n\n\u003c!-- TOC --\u003e\n\n- [About](#about)\n- [Usage](#usage)\n  - [CLI](#cli)\n  - [Docker](#docker)\n  - [Github Action](#github-action)\n- [Commands](#commands)\n  - [Examples](#examples)\n- [Releases](#releases)\n- [Development](#development)\n  - [Test DSL Syntax](#test-dsl-syntax)\n- [License](#license)\n\n\u003c!-- /TOC --\u003e\n\n## About\n\nGateway Conformance test suite is a set of tools for testing implementation\ncompliance with a subset of [IPFS Specifications](https://specs.ipfs.tech). The\ntest suite is implementation and language-agnostic. Point `gateway conformance\ntest` at HTTP endpoint and specify which tests should run.\n\nIPFS Shipyard uses it for ensuring specification compliance of the `boxo/gateway` library included in [Kubo](https://github.com/ipfs/kubo), [the most popular IPFS implementation](https://github.com/protocol/network-measurements/tree/master/reports),\nthat powers various [public gateways](https://ipfs.github.io/public-gateway-checker/), [IPFS Desktop](https://docs.ipfs.io/install/ipfs-desktop/), and [Brave](https://brave.com/ipfs-support/).\n\n\nSome scenarios in which you may find this project helpful:\n\n* You are building an product that relies on in-house IPFS Gateway and want to ensure HTTP interface is implemented correctly\n* You are building an IPFS implementation and want to leverage existing HTTP test fixtures to tell if you are handling edge cases correctly\n* You want to test if a trustless retrieval endpoint supports partial CARs from [IPIP-402](https://specs.ipfs.tech/ipips/ipip-0402/)\n* You want to confirm a commercial service provider implemented content-addressing correctly\n\n## Usage\n\nThe `gateway-conformance` can be run as a [standalone binary](#cli), a [Docker image](#docker), or a part of [Github Action](#github-actions).\n\nSome of the tests require the tested gateway to be able to resolve specific fixtures CIDs or IPNS records.\n\nTwo high level [commands](/docs/commands.md) exist:\n- [test](/docs/commands.md#test) (test runner with ability to specify a subset of tests to run)\n- [extract-fixtures](/docs/commands.md#extract-fixtures) (allowing for custom provisioning of how test vectors are loaded into tested runtime)\n\n### CLI\n\n```console\n$ # Install the gateway-conformance binary\n$ go install github.com/ipfs/gateway-conformance/cmd/gateway-conformance@latest\n\n$ # skip path gateway tests, and run subdomain-gateway tests against endpoint at http://127.0.0.1:8080 and use *.ipfs.example.com subdomains, output as JSON\n$ gateway-conformance test --gateway-url http://127.0.0.1:8080 --subdomain-url http://example.com:8080 --json report.json --specs +subdomain-gateway,-path-gateway -- -timeout 5m\n```\n\n\u003e [!TIP]\n\u003e If want skip individual tests, or only run specific ones based on a regex, see [`/docs/examples`](/docs/examples.md).\n\n### Docker\n\nThe `gateway-conformance` requires golang runtime to be present to facilitate `go test`.\nIf you want to run it on a box without having to install golang runtime, prebuilt image at `ghcr.io/ipfs/gateway-conformance` is provided.\n\nIt can be used for both `test` and `extract-fixtures` commands:\n\n```console\n$ # extract fixtures to ./extracted-fixtures directory under the current user's permissions\n$ docker run -u \"$(id -u):$(id -g)\" -v \"$(pwd):/workspace\" -w \"/workspace\" ghcr.io/ipfs/gateway-conformance:latest extract-fixtures --directory extracted-fixtures\n\n$ # skip path gateway tests, and run subdomain-gateway tests against endpoint at http://127.0.0.1:8080 and use *.ipfs.example.com subdomains, output as JSON\n$ docker run --net=host -u \"$(id -u):$(id -g)\" -v \"$(pwd):/workspace\" -w \"/workspace\" ghcr.io/ipfs/gateway-conformance:latest test --gateway-url http://127.0.0.1:8080 --subdomain-url http://example.com:8080 --json report.json --specs +subdomain-gateway,-path-gateway -- -timeout 5m\n```\n\n\u003e [!IMPORTANT]\n\u003e - for stable CI/CD, replace `latest` with a [semantic version](https://github.com/ipfs/gateway-conformance/releases) version you want to test against\n\u003e - `-u` ensures extracted fixtures and created report files can be read by your local user, make sure to adjust it to suit your use case\n\n### Github Action\n\nCommon operations are possible via reusable GitHub actions:\n- [`ipfs/gateway-conformance/.github/actions/test`](https://github.com/ipfs/gateway-conformance/blob/main/.github/actions/test/action.yml)\n- [`ipfs/gateway-conformance/.github/actions/extract-fixtures`](https://github.com/ipfs/gateway-conformance/blob/main/.github/actions/extract-fixtures/action.yml)\n\nTo learn how to integrate them in the CI of your project, see real world examples in:\n- [`kubo/../gateway-conformance.yml`](https://github.com/ipfs/kubo/blob/master/.github/workflows/gateway-conformance.yml) (fixtures imported into tested kubo node that exposes HTTP gateway feature)\n- [`boxo/../gateway-conformance.yml`](https://github.com/ipfs/boxo/blob/main/.github/workflows/gateway-conformance.yml) (fixtures imported into a sidecar kubo node that is peered with small HTTP server used for testing `boxo/gateway`  library)\n- [`rainbow/../gateway-conformance.yml`](https://github.com/ipfs/rainbow/blob/main/.github/workflows/gateway-conformance.yml) (fixtures imported into a kubo node that acts as a remote block provider, than tested against different `boxo/gateway` backends)\n\n## Commands\n\nSee `test` and `extract-fixtures` documentation at [`/docs/commands.md`](/docs/commands.md)\n\n### Examples\n\nWant to test mature specs, while disabling specific specs?\nOr only test a specific spec (like trustless gateway), while disabling a sub-part of it (only blocks and CARS, no IPNS)?\nSee [`/docs/examples.md`](/docs/examples.md)\n\n## Releases\n\nThe `main` branch may contain tests for features and IPIPs which are not yet\nsupported by stable releases of IPFS implementations.\n\nDue to this, implementations SHOULD test themselves against a stable release\nof this test suite instead.\n\nSee [`/releases`](https://github.com/ipfs/gateway-conformance/releases) for the list of available releases.\n\n## Development\n\nWant to improve the conformance test suite itself? \nSee documentation at [`/docs/development.md`](/docs/development.md)\n\n### Test DSL Syntax\n\nInterested in write a new test case?\nTest cases are written in Domain Specific Language (DLS) based on Golang.\nMore details at [`/docs/test-dsl-syntax.md`](/docs/test-dsl-syntax.md)\n\n## License\n\nThis project is dual-licensed under Apache 2.0 and MIT terms:\n\n- Apache License, Version 2.0, ([LICENSE-APACHE](https://github.com/ipfs/kubo/blob/master/LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license ([LICENSE-MIT](https://github.com/ipfs/kubo/blob/master/LICENSE-MIT) or http://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fgateway-conformance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs%2Fgateway-conformance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fgateway-conformance/lists"}