feat(contracts): add a test-utils crate

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["contracts/token", "lib/crypto", "lib/wavm-shims"]
+members = ["contracts/*", "lib/*"]
 # Explicitly set the resolver to version 2, which is the default for packages
 # with edition >= 2021.
 # https://doc.rust-lang.org/edition-guide/rust-2021/default-cargo-resolver.html

contracts/test-utils/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "test-utils"
+categories = []
+description = "Test utilities"
+edition.workspace = true
+keywords.workspace = true
+license.workspace = true
+repository.workspace = true
+version = "0.1.0"
+
+[dependencies]
+wavm-shims = { path = "../../lib/wavm-shims" }

contracts/test-utils/src/lib.rs

@@ -0,0 +1,26 @@
+//! Unit-testing utilities for Stylus contracts.
+use std::sync::{Mutex, MutexGuard};
+
+pub use wavm_shims::*;
+
+/// A global static mutex.
+///
+/// We use this for scenarios where concurrent mutation of storage is wanted.
+/// For example, when a test harness is running, this ensures each test
+/// accesses storage in an non-overlapping manner.
+///
+/// See [`with_storage`].
+pub static STORAGE_MUTEX: Mutex<()> = Mutex::new(());
+
+/// Acquires access to storage.
+pub fn acquire_storage() -> MutexGuard<'static, ()> {
+    STORAGE_MUTEX.lock().unwrap()
+}
+
+/// Decorates a closure by running it with exclusive access to storage.
+pub fn with_storage<C: Default>(closure: impl FnOnce(&mut C)) {
+    let _lock = acquire_storage();
+    let mut contract = C::default();
+    closure(&mut contract);
+    reset_storage();
+}