Create a tutorial for integration testing multiple contracts

[leighmcculloch]

What

Create a tutorial dedicated to the topic of integration testing multiple contracts together in a test.

Why

We demonstrate testing of contracts in most examples. A couple examples involve multiple contracts and also happen to demonstrate how to run integration tests where multiple contracts are in use during the test.

However, if a developer was wanting to learn how to specifically do integration testing, gazing at our docs they would probably come to the conclusion it isn't supported as there is no tutorial focused on that topic alone.

Given it is an important topic, and a topic we have good support for, we would benefit from a tutorial that focuses solely on that.

Scope

There are two ways to run integration tests, and both should be demonstrated in a tutorial:

• The "wasm" way

  The primary contract being tested is loaded natively with dependencies loaded as .wasm. The primary could also be loaded as wasm.

  Good for:

  • dependencies that are not tightly coupled to the primary
  • dependencies not developed in close proximity to the primary
  • when the source of the dependency is unavailable
  • when the source of the dependency is not trusted
  • when the test is testing an old version, or variety of versions, of a dependency

  Benefits:

  • verifies exact on chain behavior of any contract loaded as wasm
  • avoid complexity that arises from importing contracts into rust/cargo projects

• The "native" way

  The primary contract and dependencies are compiled natively as part of building the test. This requires having the source, and importing the dependency into the primary's Rust project.

  Good for:

  • dependencies that are tightly coupled to the primary and developed in close proximity
  • when the source is available and trusted
  • when testing against only a single version of a dependency

  Benefits:

  • step through debugging possible through dependencies
  • smooth development of tightly coupled multi-contract products

Both ways can be used together where tests have some dependencies as wasm and some native.

Related docs

We have a fuzz testing tutorial that was added in stellar/soroban-docs#486 (thanks @brson). Fuzz testing situations that require multiple contracts to be loaded into the VM benefit from the native testing approach, as it allows the fuzzer to identify inputs that cause branches in logic of dependencies which will help the fuzzer get increased code coverage. When we add the integration test page, we should link to the section on native testing from the fuzz testing docs.

[leighmcculloch]

cc @anupsdf

[brson]

In my fuzz testing I didn't realize it was possible to do multi-contract testing with all native contracts, and it's a surprising and useful capability. Agree this is something that needs to be emphasized.

[leighmcculloch]

it's a surprising and useful capability

Fyi it also has some surprising traps that a few folks ran into last year when we were using native testing more. Importing a contract into another contract gets funky (exported functions are included from all, and colliding function names gets interesting). This is why the current emphasis on testing with wasm, as it is much more predictable.

[leighmcculloch]

I'm iterating on a workspace example that leans into native testing rather than wasm testing:

• Add basic workspace example soroban-examples#281

[leighmcculloch]

When we add the tutorial for this, we can use the workspace example ☝🏻 to support it.