{"id":20642421,"url":"https://github.com/ipld/codec-fixtures","last_synced_at":"2025-04-16T01:41:44.584Z","repository":{"id":36970226,"uuid":"392583737","full_name":"ipld/codec-fixtures","owner":"ipld","description":"Fixtures for testing standard IPLD codecs","archived":false,"fork":false,"pushed_at":"2025-04-11T11:33:19.000Z","size":642,"stargazers_count":9,"open_issues_count":5,"forks_count":8,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-11T13:13:28.135Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/ipld.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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":"2021-08-04T06:58:08.000Z","updated_at":"2025-04-11T11:33:21.000Z","dependencies_parsed_at":"2023-02-12T23:45:19.392Z","dependency_job_id":"6f7a9144-6935-4217-b812-ed2709e0441b","html_url":"https://github.com/ipld/codec-fixtures","commit_stats":{"total_commits":124,"total_committers":8,"mean_commits":15.5,"dds":0.5403225806451613,"last_synced_commit":"204fdda3377a8d7fc2df32641d8d9ced8a990990"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fcodec-fixtures","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fcodec-fixtures/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fcodec-fixtures/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fcodec-fixtures/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipld","download_url":"https://codeload.github.com/ipld/codec-fixtures/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249182799,"owners_count":21226123,"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":[],"created_at":"2024-11-16T16:09:06.431Z","updated_at":"2025-04-16T01:41:44.575Z","avatar_url":"https://github.com/ipld.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IPLD Codec Fixtures\n\n[![Test against latest libraries](https://github.com/ipld/codec-fixtures/actions/workflows/cron.yml/badge.svg)](https://github.com/ipld/codec-fixtures/actions/workflows/cron.yml)\n\nThis repository contains fixtures for standard IPLD codecs. It is used to verify the correctness, compatibility and limitations of IPLD implementations.\n\n## What?\n\nThe [fixtures](./fixtures/) directory contains a suite of test data, where each subdirectory comprises an encoded IPLD block in the formats that are supported for that data. A file containing the binary encoded form of that block has the name `\u003cCID\u003e.\u003ccodec-name\u003e`, where the `CID` is the CIDv1 using a SHA2-256 multihash of the block for that codec. The `codec-name` is the standard codec name as found in the [multicodec table](https://github.com/multiformats/multicodec/blob/master/table.csv).\n\nFixtures are also available in CAR format, in the [./fixtures.car](./fixtures.car) file, with every valid variation stored as a separate block. (Note that this file includes blocks that may not be readable on some systems, e.g. Kubo because of the currently [unsupported Go edge cases](./go/special_cases.go)).\n\nCodec implementations are expected to be able to:\n\n1. Read and decode the IPLD block from these files\n2. Re-encode the IPLD block using the supported codecs\n3. Compare the CID of the re-encoded block to the expected CID as per the filename for the given codec\n\nSince the block is encoded in different forms, by re-encoding each decoded form into the different codecs, we are able to test the correctness of the decoding as well as the encoding process. Where the CIDs do not match, there has been a problem either in decoding or encoding the data. If the same error occurs for the data loaded from differently encoded blocks, the error is likely to be with the encoding process. If the error only occurs when re-encoding from a single encoded form of the block then the error may be with the decoding process.\n\n## Adding fixtures\n\nThe [_fixtures_src](./_fixtures_src/) directory contains the source of each of fixtures contained in the [fixtures](./fixtures/) directory. Each file in [_fixtures_src](./_fixtures_src/) contains an encoded form of a block using one of the supported codecs. The name of the file is `\u003cfixture-name\u003e.\u003ccodec-name\u003e`. The [js/make-fixtures.js](./js/make-fixtures.js) program (run with `make build`) is used to generate the fixtures in [fixtures](./fixtures/) for each of the source files.\n\nFixture generation uses the JavaScript stack for generating data, but this is not a requirement. If you would like to add fixtures and would like to create them manually, or add an alternative mechanism for generating fixtures from source then please do so.\n\n## Negative Fixtures\n\nSeparately to the _positive_ fixtures, there is a [negative-fixtures](./negative-fixtures/) directory that contains failure conditions for codecs. These don't require a compile step, so are not included in the _fixtures_src directory but are edited directly.\n\nThe structure for negative fixtures subdirectories is: `negative-fixtures/\u003ccodec name\u003e/{encode,decode}/\u003cfixtures\u003e.json`. Where `\u003ccodec name\u003e` is the canonical name of the codec being tested. `encode` and `decode` are fixtures that test the encode and decode paths of a codec, and `\u003cfixture\u003e` is an arbitrary name containing one or more fixture within the JSON structure.\n\nTest runners will load as manu fixture files as exist in these subdirectories and extract and run the cases defined there.\n\n### Encode\n\nNegative fixtures for an encode phase involve defining a data model form that should cause an error when passed through an `Encode()` for that codec. The data model form is instantiated by running the fixture data through an existing IPLD codec's decoder (mostly DAG-JSON data embedded within the JSON fixture document) and then attempting to pass that data model form into the codec and inspecting the error. Error messages may or may not be matched in some way, depending on the complexity of the implementation—it is more important that a failure occur than the error is exact.\n\n### Decode\n\nNegative fixtures for a decode phase involve loading a block's bytes from a hex form from the fixture data and passing those bytes through a `Decode()` for that codec and inspecting the error. Error messages may or may not be matched in some way, depending on the complexity of the implementation—it is more important that a failure occur than the error is exact.\n\n## Implementations \u0026 Codecs\n\n### Go\n\nFixtures are tested against the [go-ipld-prime](https://github.com/ipld/go-ipld-prime) stack:\n\n* DAG-JSON: [github.com/ipld/go-ipld-prime/codec/dagjson](https://pkg.go.dev/github.com/ipld/go-ipld-prime/codec/dagjson)\n* DAG-CBOR: [github.com/ipld/go-ipld-prime/codec/dagcbor](https://pkg.go.dev/github.com/ipld/go-ipld-prime/codec/dagcbor)\n* DAG-PB:  [github.com/ipld/go-codec-dagpb](https://pkg.go.dev/github.com/ipld/go-codec-dagpb)\n\n### JavaScript\n\nFixtures are tested against the [js-multiformats](https://github.com/multiformats/js-multiformats) stack:\n\n* DAG-CBOR: [@ipld/dag-cbor](https://github.com/ipld/js-dag-cbor)\n* DAG-JSON: [@ipld/dag-json](https://github.com/ipld/js-dag-cbor)\n* DAG-PB: [@ipld/dag-pb](https://github.com/ipld/js-dag-pb)\n\n### Rust\n\nFixtures are tested against the [libipld](https://github.com/ipld/libipld) stack:\n\n* DAG-CBOR: [libipld-cbor](https://crates.io/crates/libipld-cbor)\n* DAG-JSON: [libipld-json](https://crates.io/crates/libipld-json)\n\n### Python\n\nFixtures are tested against the [ipld-dag-pb](https://github.com/storacha/py-ipld-dag-pb)\nlibrary:\n\n* DAG-PB: [ipld-dag-pb](https://pypi.org/project/ipld-dag-pb/)\n\n## Running tests\n\n### JavaScript\n\n```\nmake testjs\n```\n\nOr, in the [js](./js/) directory, run:\n\n```\nnpm install\nnpm test\n```\n\n## Go\n\n```\nmake testgo\n```\n\nOr, in the [go](./go/) directory, run:\n\n```\ngo test\n```\n\n## Rust\n\n```\nmake testrust\n```\n\nOr in the [rust](./rust/) directory, run:\n\n```\ncargo test -- --nocapture\n```\n\n## Python\n\n```bash\nmake testpy\n```\n\nOr in the [python](./python/) directory, run:\n\n```bash\npytest\n```\n\n## Generating testmark output for ipld.io\n\nEach codec tested here has a corresponding file in the https://github.com/ipld/ipld repository which generates the https://ipld.io website containing the fixture data in [testmark](https://github.com/warpfork/go-testmark) format. The filename per codec is is `specs/codecs/\u003cCODEC\u003e/fixtures/cross-codec/index.md`.\n\nThe [js/make-testmark.js](js/make-testmark.js) program can be used to update those files when the data is updated here. Run it with `node js/make-testmark.js \u003cpath/to/ipld/ipld/repository\u003e`.\n\n## License\n\nLicensed under either of\n\n * Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / http://www.apache.org/licenses/LICENSE-2.0)\n * MIT ([LICENSE-MIT](LICENSE-MIT) / http://opensource.org/licenses/MIT)\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipld%2Fcodec-fixtures","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipld%2Fcodec-fixtures","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipld%2Fcodec-fixtures/lists"}