Skip to content

Commit

Permalink
local js test environment docs
Browse files Browse the repository at this point in the history
  • Loading branch information
petersalomonsen committed Oct 13, 2024
1 parent ec4da57 commit e736d58
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 5 deletions.
20 changes: 15 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@ https://www.youtube.com/watch?v=JBZEr__pid0&list=PLv5wm4YuO4IwVNrSsYxeqKrtQZYRML

Also check out the [end-to-end](#end-to-end-tests-using-near-workspaces) tests for how to use the contracts from this project.

# Devcontainer / github actions

All the pre-requisities for getting the project up and running can be found in the [.devcontainer](./.devcontainer) folder, which will be automaticall set up if using a github codespace.

The github actions also shows how to build and run all the examples.

# Architecture / structure

QuickJS is built with [Emscripten](https://emscripten.org/) to a static library. Another C library, which can be found in the [quickjslib](./quickjslib/) folder, is providing a simplified interface to QuickJS, which is then linked to the Rust code along with other relevant static libraries from the Emscripten distribution ( such as the C standard library, allocator, WASI etc. ).
Expand All @@ -25,10 +31,14 @@ While it's common and more straightforward for NEAR smart contracts and many oth

In the [e2e](./e2e/) folder and also within the [examples](./examples/) folders there are test files that demonstrates deployment and interaction with the contract using [near-workspaces-js](https://github.com/near/near-workspaces-js). All these tests are being run as part of the github actions pipeline, but you can also look at this for examples on how to use the contracts produced in this project.

# Local JS test environment

A simple mocking of NEAR interfaces for simulation of a smart contract directly in NodeJS or in the browser can be found in [localjstestenv](./localjstestenv/README.md).

# Example contracts

- [NFT](./examples/nft/README.md)
- [Fungible Token](./examples/fungibletoken/README.md)
- [Minimum Web4](./examples/minimumweb4/README.md)
- "[PureJS](./examples/purejs/README.md)
- [Web4 and a WebAssembly Music showcase](./web4/README.md)
- [NFT](./examples/nft/README.md) - The standard NFT contract, customizable with JavaScript
- [Fungible Token](./examples/fungibletoken/README.md) - The standard FT contract, customizable with JavaScript
- [Minimum Web4](./examples/minimumweb4/README.md) - Implement the web4 interface in JavaScript to serve a website from the smart contract
- "[PureJS](./examples/purejs/README.md)" - Precompile the JS bytecode into the contract, and provide direct exports to the JS functions.
- [Web4 and a WebAssembly Music showcase](./web4/README.md) - JavaScript from WebAssembly Music running in the smart contract
15 changes: 15 additions & 0 deletions localjstestenv/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
A minimal environment for simulation of WASM smart contracts
============================================================

Sometimes spinning up near-workspaces might not be needed if you're only going to simulate view methods or storage. By mocking the NEAR environment imports you can easily and fast spin up a smart contract runner for such simple use cases.

Given you have a simple contract `my-contract.wasm` that exports a view function named `hello`, and you can provide `name` as an argument, you can test that it returns a given value like shown in the example below.

```javascript
import { getContractInstanceExports } from "./contract-runner.js";

const { exports, nearenv } = await getContractInstanceExports(await readFile('./my-contract.wasm'));
nearenv.set_args({ name: 'peter' });
exports.hello();
expect(nearenv.latest_return_value).to.equal('hello peter');
```

0 comments on commit e736d58

Please sign in to comment.