Merge branch 'main' into feat/api-key

README.md

@@ -272,6 +272,18 @@ It is true that you can alter contract code, accounts, and access keys using nor
 
 To see an example of how to do this, see the [patch-state test](https://github.com/near/workspaces-js/blob/main/__tests__/02.patch-state.ava.ts).
 
+Time Traveling
+===============
+
+In Sandbox-mode, you can forward time-related state (the block height, timestamp and epoch height) with `fastForward`.
+
+This means contracts which require time sensitive data do not need to sit and wait the same amount of time for blocks on the sandbox to be produced.
+We can simply just call the api to get us further in time.
+
+For an example, see the [fast-forward test](./__tests__/08.fast-forward.ava.ts)
+
+Note: `fastForward` does not speed up an in-flight transactions.
+
 Pro Tips
 ========
 

__tests__/08.fast-forward.ava.ts

@@ -0,0 +1,54 @@
+import {NearAccount, getNetworkFromEnv} from 'near-workspaces';
+import anyTest, {TestFn} from 'ava';
+import {Worker} from 'near-workspaces/dist/worker';
+
+// The contract provided contains only one view call, returning the
+// block_timestamp and epoch_height of the current block as a tuple.
+// Source is here <https://github.com/near/near-workspaces-rs/blob/main/examples/simple-contract/src/lib.rs>
+const contract_wasm = '__tests__/build/debug/simple_contract.wasm';
+
+// Represents the timestamp and epoch_height result from the view call.
+type EnvData = [number, number];
+
+if (getNetworkFromEnv() === 'sandbox') {
+  const test = anyTest as TestFn<{
+    worker: Worker;
+    contract: NearAccount;
+  }>;
+
+  test.beforeEach(async t => {
+    const worker = await Worker.init();
+    const root = worker.rootAccount;
+    const contract = await root.devDeploy(contract_wasm);
+
+    t.context.worker = worker;
+    t.context.contract = contract;
+  });
+
+  test.afterEach.always(async t => {
+    await t.context.worker.tearDown().catch(error => {
+      console.log('Failed to tear down the worker:', error);
+    });
+  });
+
+  test('Fast Forward', async t => {
+    const before = await t.context.contract.view('current_env_data');
+    const env_before = before as EnvData;
+    console.log(`Before: timestamp = ${env_before[0]}, epoch_height = ${env_before[1]}`);
+
+    const forward_height = 10_000;
+
+    // Call into fastForward. This will take a bit of time to invoke, but is
+    // faster than manually waiting for the same amounts of blocks to be produced
+    await t.context.worker.provider.fastForward(forward_height);
+
+    const after = await t.context.contract.view('current_env_data');
+    const env_after = after as EnvData;
+    console.log(`After: timestamp = ${env_after[0]}, epoch_height = ${env_after[1]}`);
+
+    const block = await t.context.worker.provider.block({finality: 'final'});
+
+    // Rounding off to nearest hundred, providing wiggle room incase not perfectly `forward_height`
+    t.true(Math.ceil(block.header.height / 100) * 100 === forward_height);
+  });
+}

examples/simple-project/__tests__/test-simple-project.ava.js

@@ -0,0 +1,41 @@
+/**
+ * This test demonstrates basic behavior of near-workspaces, making simple
+ * function calls and view calls to the contract from
+ * https://github.com/near-examples/rust-status-message
+ *
+ * Note that the same tests will be run on both a local sandbox environment and
+ * on testnet by using the `test:sandbox` and `test:testnet` scripts in
+ * package.json.
+ */
+import {Worker, NEAR} from 'near-workspaces';
+import test from 'ava';
+
+test.beforeEach(async t => {
+  // Init the worker and start a Sandbox server
+  const worker = await Worker.init();
+
+  // Prepare sandbox for tests, create accounts, deploy contracts, etx.
+  const root = worker.rootAccount;
+  const contract = await root.devDeploy(
+      // source code: https://github.com/NEARFoundation/near-smart-contract-rust-template/tree/main
+    'contracts/near_smart_contract_rust_template.wasm',
+    {initialBalance: NEAR.parse('30 N').toJSON()},
+  );
+  const ali = await root.createSubAccount('ali', {initialBalance: NEAR.parse('3 N').toJSON()});
+
+  // Save state for test runs, it is unique for each test
+  t.context.worker = worker;
+  t.context.accounts = {root, contract, ali};
+});
+
+test.afterEach.always(async t => {
+  // Stop Sandbox server
+  await t.context.worker.tearDown().catch(error => {
+    console.log('Failed to tear down the worker:', error);
+  });
+});
+
+test('Root call new', async t => {
+  const {contract, ali} = t.context.accounts;
+  await ali.call(contract, 'new', {});
+});