Build and Test Packages
Once you have created a package and added a module, you can build and test your package locally to ensure it's working as expected before publishing it.
Building your package
You can use the iota move build command to build Move packages in the working directory, first_package in this case.
iota move build
If your build fails, you can use the IOTA Client's error message to troubleshoot any errors and debug your code.
If your build is successful, the IOTA client will return the following:
UPDATING GIT DEPENDENCY https://github.com/iotaledger/iota.git
INCLUDING DEPENDENCY IOTA
INCLUDING DEPENDENCY MoveStdlib
BUILDING first_package
Test a Package
You can use the Move testing framework to write unit tests for your IOTA package. IOTA includes support for the Move testing framework.
Test Syntax
You should add unit tests in their corresponding test file. In Move, test functions are identified by the following:
- They are
publicfunctions. - They have no parameters.
- They have no return values.
You can use the following command in the package root to run any unit tests you have created.
iota move test
If you haven't added any tests, you should see the following output.
INCLUDING DEPENDENCY Iota
INCLUDING DEPENDENCY MoveStdlib
BUILDING first_package
Running Move unit tests
Test result: OK. Total tests: 0; passed: 0; failed: 0
Add Tests
You can add your first unit test by copying the following public test function and adding it to the first_package file.
loading...
The unit test function test_sword() will:
- Create a dummy instance of the
TxContextstruct and assign it toctx. - Create a sword object that uses
ctxto create a unique identifier (id), and assign42to themagicparameter, and7tostrength. - Call the
magicandstrengthaccessor functions to verify that they return correct values.
The function passes the dummy context, ctx, to the object::new function as a mutable reference argument (&mut), but passes sword to its accessor functions as a read-only reference argument, &sword.
Now that you have a test function, run the test command again:
iota move test
Debugging Tests
If you run the iota move test command, you might receive the following error message instead of the test results:
error[E06001]: unused value without 'drop'
┌─ sources/first_package.move:55:65
│
4 │ public struct Sword has key, store {
│ ----- To satisfy the constraint, the 'drop' ability would need to be added here
·
48 │ let sword = Sword {
│ ----- The local variable 'sword' still contains a value. The value does not have the 'drop' ability and must be consumed before the function returns
│ ╭─────────────────────'
49 │ │ id: object::new(&mut ctx),
50 │ │ magic: 42,
51 │ │ strength: 7,
52 │ │ };
│ ╰─────────' The type 'my_first_package::first_package::Sword' does not have the ability 'drop'
· │
55 │ assert!(magic(&sword) == 42 && strength(&sword) == 7, 1);
│
The compilation error provides all the necessary information to help you debug your module.
Move has many features to ensure your code is safe. In this case, the Sword struct represents a game asset that digitally mimics a real-world item. Much like a real sword, it cannot simply disappear. Since the Sword struct doesn't have the drop ability, it has to be consumed before the function returns. However, since the sword mimics a real-world item, you don't want to allow it to disappear.
Instead, you can fix the compilation error by adequately disposing of the sword. Add the following after the function's !assert call to transfer the sword to a freshly created dummy address:
loading...
Run the test command again. Now the output shows a single successful test has run:
INCLUDING DEPENDENCY Iota
INCLUDING DEPENDENCY MoveStdlib
BUILDING my_first_package
Running Move unit tests
[ PASS ] 0x0::first_package::test_sword
Test result: OK. Total tests: 1; passed: 1; failed: 0
Use a filter string to run only a matching subset of the unit tests. With a filter string provided, the iota move test checks the fully qualified (<address>::<module_name>::<fn_name>) name for a match.
Run a Subset of Tests
You can run a subset of the tests in your package that match a given string by adding said string at the end of the iota move test command:
iota move test sword
iota move test will check the fully qualified name (<address>::<module_name>::<fn_name>) for matches. The previous command runs all tests whose name contains sword.
More Options
You can use the following command to see all the available options for the test command:
iota move test -h
- Use
iota::test_scenarioto mimic multi-transaction, multi-sender test scenarios. - Use the
iota::test_utilsmodule for better test error messages viaassert_eq, debug printing viaprint, and test-only destruction viadestroy. - Use
iota move test --coverageto compute code coverage information for your tests, andiota move coverage source --module <name>to see uncovered lines highlighted in red. Push coverage all the way to 100% if feasible.
IOTA-specific testing
Although you can test a great deal of your contract using the default Move testing framework, you should make sure that you also test code that is specific to IOTA.
Testing Transactions
Move calls in IOTA are encapsulated in transactions. You can use the iota::test_scenario to test the interactions between multiple transactions within a single test. For example, you could create an object with one transaction and transfer it to another.
The test_scenario module allows you to emulate a series of IOTA transactions. You can even assign a different user to each transaction.
Instantiate a Scenario
You can use the test_scenario::begin function to create an instance of Scenario.
The test_scenario::begin function takes an address as an argument, which will be used as the user executing the transaction.
Add More Transactions
The Scenario instance will emulate the IOTA object storage with an object pool for every address. Once you have instantiated the Scenario with the first transaction, you can use the test_scenario::next_tx function to execute subsequent transactions. You will need to pass the current Scenario instance as the first argument, as well as an address for the test user sending the transaction.
You should update the first_package.move file to include entry functions callable from IOTA that implement sword creation and transfer. You can add these after the accessor functions.
loading...
With this code, you have enabled creating and transferring a sword. Since these functions use IOTA's TxContext and Transfer, you should use the test_scenario's multi-transaction capability to test these properly. You should add the following test to the first_package.move file:
loading...
Configuration Object Creation
The create_config function allows creating reusable configuration objects that can be shared across transactions:
loading...
For The Complete tests coverage
The first_package::my_module includes a complete set of tests covering all major functionality. For complete testing coverage, refer to these test cases in the module:
loading...
This test function is more complex than the previous example, so let's break it down by steps so you understand how the test_scenario helpers work in a realistic multi-transaction flow.:
1. Create User Addresses
First, define three test addresses to represent different users in your scenario: an admin : ADMIN, an initial sword owner : ALICE, and a final sword owner : BOB.
loading...
2. Start the Scenario
Create a Scenario by calling test_scenario::begin(). Pass the admin address as the sender of the first transaction.
You can then call the init function to simulate module initialization logic during the first transaction.
loading...
3. Admin Creates a Sword and Transfers It
After the module is initialized, the admin runs a transaction to create a new sword.
Use test_scenario::next_tx to advance to the next transaction in the scenario and execute it as the admin.
In this example, the admin uses the new_sword function to create a sword using a Forge object and then transfers it to the initial_owner.
loading...
4. Initial Owner Transfers the Sword
Next, the initial_owner retrieves the sword using take_from_sender.
They then transfer the sword to the final_owner.
This works because test_scenario keeps track of objects created and transferred in earlier transactions.
loading...
Note:
Intest_scenario, transaction effects (such as creating or transferring an object) are only available to retrieve in the next transaction.If needed, you can also use
take_from_addressto fetch an object from a specific address instead of the current sender:let sword = test_scenario::take_from_address<Sword>(scenario, initial_owner);
Transaction effects, such as object creation and transfer, become visible only after a given transaction completes. For example, if the second transaction in the running example created a sword and transferred it to the administrator's address, it would only become available for retrieval from the administrator's address (via test_scenario, take_from_sender, or take_from_address functions) in the third transaction.
5. Final Owner Verifies and Cleans Up
In the final transaction, the final_owner retrieves the sword to verify its properties.
When finished, return the sword to the object pool or destroy it to keep the test state clean.
loading...
Using iota::test_utils
The iota::test_utils module provides useful helpers for assertions and cleanup.
This makes your test checks easier to read and maintain.
Key Functions:
assert_eq<T>(t1: T, t2: T)
Fails the test if t1 and t2 are not equal.
assert_same_elems<T>(v1: vector<T>, v2: vector<T>)
Checks that two vectors contain the same elements, regardless of order.
destroy<T>(x: T)
Destroys an object when you no longer need it.
Example:
loading...
Example: Complete Multi-Transaction Move Contract And Test coverage
Putting it all together, the full first_package::my_module Contract And Test coverage
function looks like this:
Inlcudes test_scenario and test_utils modules:-
loading...
Run All Tests
iota move build
iota move test
Output of the test command:
INCLUDING DEPENDENCY Iota
INCLUDING DEPENDENCY MoveStdlib
BUILDING first_package
Running Move unit tests
[ PASS ] first_package::my_module::test_address_operations
[ PASS ] first_package::my_module::test_assert_utils
[ PASS ] first_package::my_module::test_immutable_objects
[ PASS ] first_package::my_module::test_module_init
[ PASS ] first_package::my_module::test_receiving_tickets
[ PASS ] first_package::my_module::test_scenario_advanced
[ PASS ] first_package::my_module::test_sword
[ PASS ] first_package::my_module::test_sword_transactions
Test result: OK. Total tests: 8; passed: 8; failed: 0
References:
Summary
These modules help you write realistic, robust multi-transaction tests for your IOTA smart contracts. Use them together to cover advanced scenarios and keep your tests clear and maintainable.