Nearsighted Paramecium Multiverse

    TypeScript icon, indicating that this package has built-in type declarations

    10.0.0 • Public • Published

    ipfs-interop IRC Discord codecov CI

    Interoperability Tests for IPFS

    Table of contents


    $ npm i ipfs-interop

    This repository will be used for interop tests. Please jump into the issues if you'd like to help out setting this up!


    Run the tests

    $ ipfs-interop

    Run a particular test locally

    $ node bin/ipfs-interop.js -- -t node --grep {substring-test-name}

    Testing with different versions of go/js IPFS

    As a project

    This module declares peer dependencies of ipfs, ipfs-http-client, kubo-rpc-client and go-ipfs so if you have ipfs-interop as a dependecy of your project, simply add the extra IPFS dependencies:

      "name": "my-project",
      "scripts": {
        "interop": "ipfs-interop"
      "dependencies": {
        "go-ipfs": "...",
        "ipfs": "...",
        "ipfs-http-client": "...",
        "ipfs-interop": "...",
        "kubo-rpc-client": "..."

    Then run:

    $ npm run interop

    As environmental variables

    Specify the following environmental variables to control which versions of IPFS ipfs-interop uses when installed globally:

    • IPFS_GO_EXEC A path to a go-IPFS binary
    • IPFS_JS_EXEC A path to /src/cli.js inside a js-IPFS install
    • IPFS_JS_MODULE A path to a js-IPFS install
    • IPFS_JS_HTTP_MODULE A path to a ipfs-http-client install (optional)
    • KUBO_RPC_MODULE A path to a kubo-rpc-client install (optional)

    Then run:

    $ npm install -g ipfs-interop
    $ IPFS_GO_EXEC=/path IPFS_JS_EXEC=/path IPFS_JS_MODULE=/path IPFS_JS_HTTP_MODULE=/path ipfs-interop

    As a custom runtime

    If you want to run interop on CI against specific repo and git revision of go-ipfs or js-ipfs* then set everything up in ./scripts/ and enable it by uncommenting env: IPFS_(..) definitions in .github/workflows/test.yml

    If you want to test against unrelased things locally, make sure the same env variables are set on your machine.

    For example, to run pubsub tests against go-ipfs and js-ipfs revision defined in ./scripts/, one can:

    export IPFS_GO_EXEC=/tmp/go-ipfs/cmd/ipfs/ipfs
    export IPFS_JS_EXEC=/tmp/js-ipfs/packages/ipfs/src/cli.js
    export IPFS_JS_MODULE=/tmp/js-ipfs/packages/ipfs/src/index.js
    export IPFS_JS_HTTP_MODULE=/tmp/js-ipfs/packages/ipfs-http-client/src/index.js
    export KUBO_RPC_MODULE=/tmp/kubo-rpc-client/src/index.js
    node bin/ipfs-interop.js -- -t node --grep "pubsub"

    Releasing a new version

    This repo does not use aegir for releases. Use npm directly and publish entire root (CI in go-ipfs requires it).

    npm version [major|minor|patch]
    npm publish
    npm push origin && npm push origin v[N.N.N]

    Interop release process for when breaking changes are introduced

    1. Get branches of go-ipfs and js-ipfs working together in interop locally using environment variables to point at the local versions
    2. In this repo make a branch containing the interop changes as well as setting the go/js-ipfs commit hashes to be used by CI. Merge to master.
    3. Update go-ipfs and js-ipfs branches to use interop/master instead of whatever is released
    4. Release go and js-ipfs (not necessarily together) and after each is released (or RC'd) bump interop to use the release instead of the commit hash
    5. Release interop
    6. Bump go and js-ipfs to use released interop instead of master


    Licensed under either of


    Feel free to join in. All welcome. Open an issue!

    This repository falls under the IPFS Code of Conduct.



    npm i ipfs-interop

    DownloadsWeekly Downloads





    Apache-2.0 OR MIT

    Unpacked Size

    2.17 MB

    Total Files


    Last publish


    • jacobheun
    • achingbrain
    • lidel
    • ipfs-npm-publisher-bot
    • npm-service-account-ipfs