Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create a tutorial for integration testing multiple contracts #481

Open
leighmcculloch opened this issue Aug 23, 2023 · 5 comments
Open

Create a tutorial for integration testing multiple contracts #481

leighmcculloch opened this issue Aug 23, 2023 · 5 comments
Assignees

Comments

@leighmcculloch
Copy link
Member

leighmcculloch commented Aug 23, 2023

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 using contractimport!. 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-deprecated/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
Copy link
Member Author

cc @anupsdf

@brson
Copy link
Contributor

brson commented Aug 26, 2023

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
Copy link
Member Author

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
Copy link
Member Author

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

@leighmcculloch
Copy link
Member Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Backlog
Development

No branches or pull requests

5 participants
@brson @leighmcculloch @janewang @ElliotFriend and others