ipfs-interop

Interoperability Tests for IPFS

Table of contents

• Install
• Usage
  • Run the tests
  • Run a particular test locally
• Testing with different versions of go/js IPFS
  • As a project
  • As environmental variables
  • As a custom runtime
• Releasing a new version
• Interop release process for when breaking changes are introduced
• License
• Contribute

Install

$ 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!

Usage

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/custom-runtime.sh 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/custom-runtime.sh, 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
./scripts/custom-runtime.sh
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

License

Licensed under either of

• Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
• MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)

Contribute

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

This repository falls under the IPFS Code of Conduct.