示例

更多独立示例可以在 examples/src/*.rs 中找到。

要运行上述NFT示例，执行

cargo run --example nft

功能

选择网络

#[tokio::main]  // or whatever runtime we want
async fn main() -> anyhow::Result<()> {
    // Create a sandboxed environment.
    // NOTE: Each call will create a new sandboxed environment
    let worker = near_workspaces::sandbox().await?;
    // or for testnet:
    let worker = near_workspaces::testnet().await?;
}

辅助函数

需要使用合约创建辅助函数？只需导入它并传递它

use near_workspaces::Contract;

// Helper function that calls into a contract we give it
async fn call_my_func(contract: &Contract) -> anyhow::Result<()> {
    // Call into the function `contract_function` with args:
    contract.call("contract_function")
        .args_json(serde_json::json!({
            "message": msg,
        })
        .transact()
        .await?;
    Ok(())
}

或无论网络如何传递工作者

use near_workspaces::{DevNetwork, Worker};

const CONTRACT_BYTES: &[u8] = include_bytes!("./relative/path/to/file.wasm");

// Create a helper function that deploys a specific contract
// NOTE: `dev_deploy` is only available on `DevNetwork`s such as sandbox and testnet.
async fn deploy_my_contract(worker: Worker<impl DevNetwork>) -> anyhow::Result<Contract> {
    worker.dev_deploy(CONTRACT_BYTES).await
}

查看账户详情

我们可以这样检查我们的账户余额

#[test(tokio::test)]
async fn test_contract_transfer() -> anyhow::Result<()> {
    let transfer_amount = NearToken::from_millinear(100);
    let worker = near_workspaces::sandbox().await?;

    let contract = worker
        .dev_deploy(include_bytes!("../target/res/your_project_name.wasm"))
        .await?;
    contract.call("new")
        .max_gas()
        .transact()
        .await?;

    let alice = worker.dev_create_account().await?;
    let bob = worker.dev_create_account().await?;
    let bob_original_balance = bob.view_account().await?.balance;

    alice.call(contract.id(), "function_that_transfers")
        .args_json(json!({ "destination_account": bob.id() }))
        .max_gas()
        .deposit(transfer_amount)
        .transact()
        .await?;
    assert_eq!(
        bob.view_account().await?.balance,
        bob_original_balance + transfer_amount
    );

    Ok(())
}

对于查看其他链相关详情，请参阅 Worker、Account 和 Contract 的文档

抄袭 - 从主网/测试网拉取现有状态和合约

此示例将展示将测试网合约的状态拉入我们的本地沙盒环境。

我们首先从通常的导入开始

use near_workspaces::network::Sandbox;
use near_workspaces::{Account, AccountId, BlockHeight, Contract, Worker};

然后指定我们想要从测试网拉取的合约名称

const CONTRACT_ACCOUNT: &str = "contract_account_name_on_testnet.testnet";

让我们还指定一个特定的区块ID，它引用回一个特定的时间。以防我们的合约或我们引用的合约已更改或更新

const BLOCK_HEIGHT: BlockHeight = 12345;

创建一个名为 pull_contract 的函数，它将从链上拉取合约的 .wasm 文件并将其部署到我们的本地沙盒。我们将必须使用所有数据重新初始化它以运行测试。

async fn pull_contract(owner: &Account, worker: &Worker<Sandbox>) -> anyhow::Result<Contract> {
    let testnet = near_workspaces::testnet_archival().await?;
    let contract_id: AccountId = CONTRACT_ACCOUNT.parse()?;

此行将实际上从测试网拉下相关的合约，并在其上设置1000 NEAR的初始余额。

接下来，我们需要再次使用我们自己的元数据初始化合约。这是因为合约的数据太大，无法通过RPC服务下载，其限制为50kb。

    use near_workspaces::types::NearToken;
    let contract = worker
        .import_contract(&contract_id, &testnet)
        .initial_balance(NearToken::from_near(1000))
        .block_height(BLOCK_HEIGHT)
        .transact()
        .await?;

    owner
        .call(contract.id(), "init_method_name")
        .args_json(serde_json::json!({
            "arg1": value1,
            "arg2": value2,
        }))
        .transact()
        .await?;

    Ok(contract)
}

时间旅行

workspaces 测试提供将区块链状态转发到未来的支持。这意味着需要时间敏感数据的合约不需要等待与沙盒中生成的块相同的时间。我们可以简单地调用 worker.fast_forward 来进一步推进时间。注意：这不会加快当前正在进行的交易的速度；这里所说的状态是指与时间相关的状态（区块高度、时间戳和纪元）。

#[tokio::test]
async fn test_contract() -> anyhow::Result<()> {
    let worker = near_workspaces::sandbox().await?;
    let contract = worker.dev_deploy(WASM_BYTES).await?;

    let blocks_to_advance = 10000;
    worker.fast_forward(blocks_to_advance).await?;

    // Now, "do_something_with_time" will be in the future and can act on future time-related state.
    contract.call("do_something_with_time")
        .transact()
        .await?;
}

对于完整示例，请参阅 examples/src/fast_forward.rs。

测试期间编译合约

注意，这是一个不稳定的特性，很可能会有所变化。要启用它，请在 Cargo.toml 中的 workspaces 依赖项中添加 unstable 功能标志

[dependencies]
near-workspaces = { version = "...", features = ["unstable"] }

然后，在我们的测试中，在我们调用 deploy 或 dev_deploy 之前，我们可以编译我们的项目

#[tokio::test]
async fn test_contract() -> anyhow::Result<()> {
    let wasm = near_workspaces::compile_project("path/to/contract-rs-project").await?;

    let worker = workspaces::sandbox().await?;
    let contract = worker.dev_deploy(&wasm).await?;
    ...
}

对于完整示例，请参阅 workspaces/tests/deploy_project.rs。

WASM可执行文件覆盖率分析

生成的代码覆盖率报告有助于识别测试期间执行的代码区域，因此它是一个确保合约可靠性和质量的有价值工具。有关实现此功能的步骤指南文档 在这里。

项目可以在以下位置找到： https://github.com/hknio/wasmcov

其他功能

其他功能可以直接在 examples/ 文件夹中找到，其中一些文档说明了如何使用它们。

环境变量

如果有任何问题，以下环境变量将非常有用

• NEAR_RPC_TIMEOUT_SECS：默认为10秒，但这是在与沙盒或任何其他网络（如测试网）通信时等待RPC服务超时之前的时间。
• NEAR_SANDBOX_BIN_PATH：如果我们想使用非默认版本的沙盒或配置 nearcore 以测试我们想在 near-workspaces 中测试的自定义功能，请将此设置为我们的预构建 neard-sandbox bin 路径。
• NEAR_SANDBOX_MAX_PAYLOAD_SIZE：设置向沙盒发送事务提交的最大有效载荷大小。默认为1gb，这对于修补大型状态是必要的。
• NEAR_SANDBOX_MAX_FILES：设置沙盒中一次可以打开的最大文件数。如果没有指定，则默认大小为4096。实际近链将使用超过10,000，但在测试中这应该要低得多，因为我们没有持续运行的区块链，除非我们的测试需要那么长时间。
• NEAR_RPC_API_KEY：这是与RPC节点通信所需的API密钥。这对于与Pagoda控制台或可以访问RPC指标的服务交互非常有用。这不是一个 强制 要求，但建议在示例文件夹中运行Pagoda示例时使用。
• NEAR_ENABLE_SANDBOX_LOG：将此设置为 1 以启用沙盒日志记录。这对于调试与 neard-sandbox 二进制文件相关的问题非常有用。