Docs
⌘ K

34 分钟

单元测试框架

学习如何使用 Matchstick，一个由 [LimeChain]开发的单元测试框架(https://limechain.tech/)。⁠ Matchstick使子图开发者能够在沙盒环境中测试其绘图逻辑并成功地部署其子图。

使用Matchstick的好处

  • 它用Rust编写并优化高性能。
  • 它允许您访问开发者功能，包括模拟合约通话的能力 对商店状态进行断言、监视子图失败、检查测试性能等等。

开始

安装依赖项

为了使用测试辅助器方法并运行测试，您需要安装以下依赖项：

yarn add --dev matchstick-as

安装PostgreSQL

graph-node依赖于PostgreSQL，所以如果你还没有它，你将需要安装它。

注意：强烈建议使用下面的命令来避免意外错误。

使用 MacOS

安装命令：

酿造安装postgresql

创建到最新 libpq.5. lib 的符号链接，可能需要首先创建这个目录/usr/local/opt/postgreql/lib/`

ln -sf /usr/local/opt/postgresql@14/lib/postgresql@14/libpq.5.dylib /usr/local/opt/postgresql/lib/libpq.5.dylib

使用 Linux

安装命令(取决于您的拆分)：

sudo apt install postgresql

使用 WSL (window子系统为 Linux)

可以使用 Docker 方法和二进制方法在 WSL 上使用 Matchstick。由于 WSL 可能有点复杂，所以这里有一些提示，以防您遇到诸如

static BYTES = Symbol("Bytes") SyntaxError: Unexpected token =

或者

<PROJECT_PATH>/node_modules/gluegun/build/index.js:13 throw up;

请确保您是新版本的 Node.js graph-cli 不支持 v10.19.0 ，这仍然是WSL上新的 Ubuntu 图像的默认版本。 例如，Matchstick被确认在 WSL 使用 **v18.1.0 **，您可以通过 nvm 切换到它，也可以更新您的全局Node.js。 别忘了在更新节点后删除 node_modules 并重新运行 npm install ！ 然后，请确保您已经安装了 libpq ，您可以通过运行来做到这一点。

sudo apt-get install libpq-dev

最后， 不要使用 graph test (它使用您的全局安装图形-cli ，并且出于某些原因看起来像当前WSL 上的故障)， 相反，使用 yarn test 或 npm 运行测试 (这将使用当地、项目一级的graph-cli 实例，它类似于一个字符)。 因此，你当然需要在你的package.json 文件中有一个 “test"" 脚本，这个脚本可以像这样简单。

{  "name": "demo-subgraph",  "version": "0.1.0",  "scripts": {    "test": "graph test",    ...  },  "dependencies": {    "@graphprotocol/graph-cli": "^0.56.0",    "@graphprotocol/graph-ts": "^0.31.0",    "matchstick-as": "^0.6.0"  }}

使用 Matchstick

要在子图项目中使用Matchstick，只需打开一个终端，导航到项目的根文件夹，然后简单地运行graph test [options] <datasource>-它下载最新的Matchstick二进制文件，并在测试文件夹中运行指定的测试或所有测试（如果未指定数据源标志，则运行所有现有测试）。

CLI 选项

这将运行测试文件夹中的所有测试：

graph test

这将运行名为gravity.test.ts的测试和/或名为gravity的文件夹中的所有测试：

graph test Gravity

这将仅运行特定的测试文件：

graph test path/to/file.test.ts

选项:

-c, --coverage                Run the tests in coverage mode-d, --docker                  Run the tests in a docker container (Note: Please execute from the root folder of the Subgraph)-f, --force                   Binary: Redownloads the binary. Docker: Redownloads the Dockerfile and rebuilds the docker image.-h, --help                    Show usage information-l, --logs                    Logs to the console information about the OS, CPU model and download url (debugging purposes)-r, --recompile               Forces tests to be recompiled-v, --version <tag>           Choose the version of the rust binary that you want to be downloaded/used

Docker

从 graph-cli 0.25.2, graph test 命令支持使用 -d 标志在一个码头容器中运行 matchstick 。 停泊器实现使用 绑定挂载⁠，所以它不必在执行”Graph test -d” 命令时重建停泊器图像。 你也可以按照 matchstick⁠的指令手动运行停靠仓库。

❗ graph test -d 强制docker run 使用标志-t运行。这必须移除以在非交互环境中运行(如GitHub CI)。

❗ 如果你以前运行过graph test, 在docker构建过程中可能会遇到以下错误：

error from sender: failed to xattr node_modules/binary-install-raw/bin/binary-<platform>: permission denied

在这种情况下，在根文件夹中创建 .dockerignore 并添加 node_modules/biny-install-raw/bin。

配置

Matchstick可以通过matchstick.yaml配置文件配置为使用自定义测试、库和清单路径：

testsFolder: path/to/testslibsFolder: path/to/libsmanifestPath: path/to/subgraph.yaml

演示子图

你可以尝试通过克隆Demo Subgraph repo⁠ 来使用本指南的示例。

视频教程

此外，您还可以查看“如何使用Matchstick为子图编写单元测试”系列视频⁠。

测试结构

IMPORTANT：下面描述的测试结构取决于matchstick-as版本 >=0.5.0

描述（）

description(name: String , () => {}) - 定义测试组。

注意:

  • 描述不是强制性的。您仍然可以在describe（）区块之外，以旧的方式使用test（）

例子:

import { describe, test } from "matchstick-as/assembly/index"import { handleNewGravatar } from "../../src/gravity"describe("handleNewGravatar()", () => {  test("Should create a new Gravatar entity", () => {    ...  })})

嵌套的 descrip() 示例：

import { describe, test } from "matchstick-as/assembly/index"import { handleUpdatedGravatar } from "../../src/gravity"describe("handleUpdatedGravatar()", () => {  describe("When entity exists", () => {    test("updates the entity", () => {      ...    })  })  describe("When entity does not exists", () => {    test("it creates a new entity", () => {      ...    })  })})

测试（）

test(name: String, () =>, should_fail: bool) - 定义测试案例。您可以在描述() 块内或独立使用test()。

例子:

import { describe, test } from "matchstick-as/assembly/index"import { handleNewGravatar } from "../../src/gravity"describe("handleNewGravatar()", () => {  test("Should create a new Entity", () => {    ...  })})

或者

test("handleNewGravatar() should create a new entity", () => {  ...})

beforeAll()

在文件中的任何测试之前运行代码区块。如果beforeAll在describe区块内声明，它将在该describe区块的开头运行。

例子：

beforeAll中的代码将在第一个描述区块中的所有测试之前执行一次。

import { describe, test, beforeAll } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"import { Gravatar } from "../../generated/schema"beforeAll(() => {  let gravatar = new Gravatar("0x0")  gravatar.displayName = “First Gravatar”  gravatar.save()  ...})describe("When the entity does not exist", () => {  test("it should create a new Gravatar with id 0x1", () => {    ...  })})describe("When entity already exists", () => {  test("it should update the Gravatar with id 0x0", () => {    ...  })})

beforeAll中的代码将在第一个描述区块中的所有测试之前执行一次。

import { describe, test, beforeAll } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"import { Gravatar } from "../../generated/schema"describe("handleUpdatedGravatar()", () => {  beforeAll(() => {    let gravatar = new Gravatar("0x0")    gravatar.displayName = “First Gravatar”    gravatar.save()    ...  })  test("updates Gravatar with id 0x0", () => {    ...  })  test("creates new Gravatar with id 0x1", () => {    ...  })})

afterAll()

在每次测试后运行代码区块。如果afterAll在describe 区块中声明，则在该describe 区块中的每个测试之后运行。

例子:

afterAll中的代码将在第一个描述区块中的所有测试之后执行一次。

import { describe, test, afterAll } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"import { store } from "@graphprotocol/graph-ts"afterAll(() => {  store.remove("Gravatar", "0x0")  ...})describe("handleNewGravatar, () => {  test("creates Gravatar with id 0x0", () => {    ...  })})describe("handleUpdatedGravatar", () => {  test("updates Gravatar with id 0x0", () => {    ...  })})

afterAll中的代码将在第一个描述区块中的所有测试之后执行一次。

import { describe, test, afterAll, clearStore } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"describe("handleNewGravatar", () => {	afterAll(() => {    store.remove("Gravatar", "0x1")    ...	})  test("It creates a new entity with Id 0x0", () => {    ...  })  test("It creates a new entity with Id 0x1", () => {    ...  })})describe("handleUpdatedGravatar", () => {  test("updates Gravatar with id 0x0", () => {    ...  })})

beforeEach()

在文件中的任何测试之前运行代码区块。如果beforeEach在describe区块内声明，它将在该describe区块的每次测试之前运行。

示例：在每次测试之前，beforeEach中的代码将会执行。

import { describe, test, beforeEach, clearStore } from "matchstick-as/assembly/index"import { handleNewGravatars } from "./utils"beforeEach(() => {  clearStore() // <-- clear the store before each test in the file})describe("handleNewGravatars, () => {  test("A test that requires a clean store", () => {    ...  })  test("Second that requires a clean store", () => {    ...  })}) ...

beforeEach 里的代码将仅在描述中的每个测试之前执行。

import { describe, test, beforeEach } from 'matchstick-as/assembly/index'import { handleUpdatedGravatar, handleNewGravatar } from '../../src/gravity'describe('handleUpdatedGravatars', () => {  beforeEach(() => {    let gravatar = new Gravatar('0x0')    gravatar.displayName = 'First Gravatar'    gravatar.imageUrl = ''    gravatar.save()  })  test('Updates the displayName', () => {    assert.fieldEquals('Gravatar', '0x0', 'displayName', 'First Gravatar')    // code that should update the displayName to 1st Gravatar    assert.fieldEquals('Gravatar', '0x0', 'displayName', '1st Gravatar')    store.remove('Gravatar', '0x0')  })  test('Updates the imageUrl', () => {    assert.fieldEquals('Gravatar', '0x0', 'imageUrl', '')    // code that should changes the imageUrl to https://www.gravatar.com/avatar/0x0    assert.fieldEquals('Gravatar', '0x0', 'imageUrl', 'https://www.gravatar.com/avatar/0x0')    store.remove('Gravatar', '0x0')  })})

afterEach()

在文件中的任何测试之前运行代码区块。如果beforeEach在describe区块内声明，它将在该describe区块的每次测试之前运行。

例子：

AfterEach中的代码将仅在描述中的每个测试之后执行。

import { describe, test, beforeEach, afterEach } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"beforeEach(() => {  let gravatar = new Gravatar("0x0")  gravatar.displayName = “First Gravatar”  gravatar.save()})afterEach(() => {  store.remove("Gravatar", "0x0")})describe("handleNewGravatar", () => {  ...})describe("handleUpdatedGravatar", () => {  test("Updates the displayName", () => {     assert.fieldEquals("Gravatar", "0x0", "displayName", "First Gravatar")    // code that should update the displayName to 1st Gravatar    assert.fieldEquals("Gravatar", "0x0", "displayName", "1st Gravatar")  })  test("Updates the imageUrl", () => {    assert.fieldEquals("Gravatar", "0x0", "imageUrl", "")    // code that should changes the imageUrl to https://www.gravatar.com/avatar/0x0    assert.fieldEquals("Gravatar", "0x0", "imageUrl", "https://www.gravatar.com/avatar/0x0")  })})

AfterEach中的代码将仅在描述中的每个测试之后执行。

import { describe, test, beforeEach, afterEach } from "matchstick-as/assembly/index"import { handleUpdatedGravatar, handleNewGravatar } from "../../src/gravity"describe("handleNewGravatar", () => {  ...})describe("handleUpdatedGravatar", () => {  beforeEach(() => {    let gravatar = new Gravatar("0x0")    gravatar.displayName = "First Gravatar"    gravatar.imageUrl = ""    gravatar.save()  })  afterEach(() => {    store.remove("Gravatar", "0x0")  })  test("Updates the displayName", () => {     assert.fieldEquals("Gravatar", "0x0", "displayName", "First Gravatar")    // code that should update the displayName to 1st Gravatar    assert.fieldEquals("Gravatar", "0x0", "displayName", "1st Gravatar")  })  test("Updates the imageUrl", () => {    assert.fieldEquals("Gravatar", "0x0", "imageUrl", "")    // code that should changes the imageUrl to https://www.gravatar.com/avatar/0x0    assert.fieldEquals("Gravatar", "0x0", "imageUrl", "https://www.gravatar.com/avatar/0x0")  })})

判断

fieldEquals(entityType: string, id: string, fieldName: string, expectedVal: string)equals(expected: ethereum.Value, actual: ethereum.Value)notInStore(entityType: string, id: string)addressEquals(address1: Address, address2: Address)bytesEquals(bytes1: Bytes, bytes2: Bytes)i32Equals(number1: i32, number2: i32)bigIntEquals(bigInt1: BigInt, bigInt2: BigInt)booleanEquals(bool1: boolean, bool2: boolean)stringEquals(string1: string, string2: string)arrayEquals(array1: Array<ethereum.Value>, array2: Array<ethereum.Value>)tupleEquals(tuple1: ethereum.Tuple, tuple2: ethereum.Tuple)assertTrue(value: boolean)assertNull<T>(value: T)assertNotNull<T>(value: T)entityCount(entityType: string, expectedCount: i32)

截至版本 0.6.0，我们也支持自定义错误消息。

assert.fieldEquals('Gravatar', '0x123', 'id', '0x123', 'Id should be 0x123')assert.equals(ethereum.Value.fromI32(1), ethereum.Value.fromI32(1), 'Value should equal 1')assert.notInStore('Gravatar', '0x124', 'Gravatar should not be in store')assert.addressEquals(Address.zero(), Address.zero(), 'Address should be zero')assert.bytesEquals(Bytes.fromUTF8('0x123'), Bytes.fromUTF8('0x123'), 'Bytes should be equal')assert.i32Equals(2, 2, 'I32 should equal 2')assert.bigIntEquals(BigInt.fromI32(1), BigInt.fromI32(1), 'BigInt should equal 1')assert.booleanEquals(true, true, 'Boolean should be true')assert.stringEquals('1', '1', 'String should equal 1')assert.arrayEquals([ethereum.Value.fromI32(1)], [ethereum.Value.fromI32(1)], 'Arrays should be equal')assert.tupleEquals(  changetype<ethereum.Tuple>([ethereum.Value.fromI32(1)]),  changetype<ethereum.Tuple>([ethereum.Value.fromI32(1)]),  'Tuples should be equal',)assert.assertTrue(true, 'Should be true')assert.assertNull(null, 'Should be null')assert.assertNotNull('not null', 'Should be not null')assert.entityCount('Gravatar', 1, 'There should be 2 gravatars')assert.dataSourceCount('GraphTokenLockWallet', 1, 'GraphTokenLockWallet template should have one data source')assert.dataSourceExists(  'GraphTokenLockWallet',  Address.zero().toHexString(),  'GraphTokenLockWallet should have a data source for zero address',)

编写一个单元测试

让我们看看一个简单的单元测试，如何看起来像在 Demo Subgraph⁠中使用 Gravatar 示例。

假设我们有以下处理程序函数（以及两个帮助函数，以使我们的生活更轻松）：

export function handleNewGravatar(event: NewGravatar): void {  let gravatar = new Gravatar(event.params.id.toHex())  gravatar.owner = event.params.owner  gravatar.displayName = event.params.displayName  gravatar.imageUrl = event.params.imageUrl  gravatar.save()}export function handleNewGravatars(events: NewGravatar[]): void {  events.forEach((event) => {    handleNewGravatar(event)  })}export function createNewGravatarEvent(  id: i32,  ownerAddress: string,  displayName: string,  imageUrl: string,): NewGravatar {  let mockEvent = newMockEvent()  let newGravatarEvent = new NewGravatar(    mockEvent.address,    mockEvent.logIndex,    mockEvent.transactionLogIndex,    mockEvent.logType,    mockEvent.block,    mockEvent.transaction,    mockEvent.parameters,  )  newGravatarEvent.parameters = new Array()  let idParam = new ethereum.EventParam('id', ethereum.Value.fromI32(id))  let addressParam = new ethereum.EventParam(    'ownerAddress',    ethereum.Value.fromAddress(Address.fromString(ownerAddress)),  )  let displayNameParam = new ethereum.EventParam('displayName', ethereum.Value.fromString(displayName))  let imageUrlParam = new ethereum.EventParam('imageUrl', ethereum.Value.fromString(imageUrl))  newGravatarEvent.parameters.push(idParam)  newGravatarEvent.parameters.push(addressParam)  newGravatarEvent.parameters.push(displayNameParam)  newGravatarEvent.parameters.push(imageUrlParam)  return newGravatarEvent}

我们首先必须在项目中创建一个测试文件。这是一个示例，说明它可能是什么样子的：

import { clearStore, test, assert } from 'matchstick-as/assembly/index'import { Gravatar } from '../../generated/schema'import { NewGravatar } from '../../generated/Gravity/Gravity'import { createNewGravatarEvent, handleNewGravatars } from '../mappings/gravity'test('Can call mappings with custom events', () => {  // Create a test entity and save it in the store as initial state (optional)  let gravatar = new Gravatar('gravatarId0')  gravatar.save()  // Create mock events  let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')  let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')  // Call mapping functions passing the events we just created  handleNewGravatars([newGravatarEvent, anotherGravatarEvent])  // Assert the state of the store  assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0')  assert.fieldEquals('Gravatar', '12345', 'owner', '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7')  assert.fieldEquals('Gravatar', '3546', 'displayName', 'cap')  // Clear the store in order to start the next test off on a clean slate  clearStore()})test('Next test', () => {  //...})

还有很多东西可以解包！ 首先，我们注意到的一个重要问题是，我们正在从 matchstick-as、我们的 AssemblyScript 助手库中导入一些东西(作为npm 模块分发)。 您可以在这里⁠找到仓库。 matchstick-as为我们提供了有用的测试方法，并定义了test()功能，我们将用它来构建我们的测试块。 其它部分相当直截了当――这里发生了什么事：

  • 我们正在设置我们的初始状态并添加一个自定义的 Gravatar 实体。
  • 我们使用 createNewGravatarEvent() 函数定义两个NewGravatar事件对象及其数据；
  • 我们正在调用这些事件的处理方法 - handleNewGravatars() 并在我们的自定义事件列表中传递；
  • 我们断定存储的状态。那是怎么实现的呢？- 我们传递一个实体类型和 id 的唯一组合。然后我们检查该实体的一个特定字段，并断定它具有我们期望的值。我们为我们添加到存储的初始 Gravatar 实体，以及当处理函数被调用时被添加的两个 Gravatar 实体都做这个。
  • 最后——我们正在使用 clearStore() 来清理内存，以便我们的下一次测试能够以一个新的和空的储存对象开始。 我们可以定义我们想要的尽可能多的试验区块。

好了，我们创建了第一个测试！👏

现在，为了运行我们的测试，您只需在子图根文件夹中运行以下命令：

graph test Gravity

如果一切顺利，您应该会收到以下信息：

Matchstick表示“通过所有测试！”

常见测试场景

使用特定状态来填充存储

用户能够用一组已知的实体来补充存储。下面是一个用Gravatar实体初始化存储的例子。

let gravatar = new Gravatar('entryId')gravatar.save()

用一个事件调用一个映射函数

用户可以创建自定义事件并将其传递给绑定到存储的映射函数：

import { store } from 'matchstick-as/assembly/store'import { NewGravatar } from '../../generated/Gravity/Gravity'import { handleNewGravatars, createNewGravatarEvent } from './mapping'let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')handleNewGravatar(newGravatarEvent)

用事件夹具调用所有的映射关系

用户可以用测试夹具调用所有的映射关系。

import { NewGravatar } from '../../generated/Gravity/Gravity'import { store } from 'matchstick-as/assembly/store'import { handleNewGravatars, createNewGravatarEvent } from './mapping'let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac')handleNewGravatars([newGravatarEvent, anotherGravatarEvent])
export function handleNewGravatars(events: NewGravatar[]): void {    events.forEach(event => {        handleNewGravatar(event);    });}

模拟合约调用

用户可以模拟合约调用：

import { addMetadata, assert, createMockedFunction, clearStore, test } from 'matchstick-as/assembly/index'import { Gravity } from '../../generated/Gravity/Gravity'import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts'let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7')let expectedResult = Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947')let bigIntParam = BigInt.fromString('1234')createMockedFunction(contractAddress, 'gravatarToOwner', 'gravatarToOwner(uint256):(address)')  .withArgs([ethereum.Value.fromSignedBigInt(bigIntParam)])  .returns([ethereum.Value.fromAddress(Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947'))])let gravity = Gravity.bind(contractAddress)let result = gravity.gravatarToOwner(bigIntParam)assert.equals(ethereum.Value.fromAddress(expectedResult), ethereum.Value.fromAddress(result))

如图所示，为了模拟合约调用并实现返回值，用户必须提供合约地址、函数名、函数签名、参数数组，当然还有返回值。

用户还可以模拟函数还原：

let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7')createMockedFunction(contractAddress, 'getGravatar', 'getGravatar(address):(string,string)')  .withArgs([ethereum.Value.fromAddress(contractAddress)])  .reverts()

模拟IPFS文件(from matchstick 0.4.1)

用户可以使用 mockIpfsFile(hash, filePath) 函数模拟IPFS 文件。 函数接受两个参数，第一个参数是IPFS 文件哈希/路径，第二个参数是本地文件的路径。

注意：在测试ipfs.map/ipfs.mapJSON,时，必须从测试文件中导出回调函数，以便matchstck检测到它，如下面测试示例中的processGravatar() 函数：

.test.ts file:

import { assert, test, mockIpfsFile } from 'matchstick-as/assembly/index'import { ipfs } from '@graphprotocol/graph-ts'import { gravatarFromIpfs } from './utils'// Export ipfs.map() callback in order for matchstick to detect itexport { processGravatar } from './utils'test('ipfs.cat', () => {  mockIpfsFile('ipfsCatfileHash', 'tests/ipfs/cat.json')  assert.entityCount(GRAVATAR_ENTITY_TYPE, 0)  gravatarFromIpfs()  assert.entityCount(GRAVATAR_ENTITY_TYPE, 1)  assert.fieldEquals(GRAVATAR_ENTITY_TYPE, '1', 'imageUrl', 'https://i.ytimg.com/vi/MELP46s8Cic/maxresdefault.jpg')  clearStore()})test('ipfs.map', () => {  mockIpfsFile('ipfsMapfileHash', 'tests/ipfs/map.json')  assert.entityCount(GRAVATAR_ENTITY_TYPE, 0)  ipfs.map('ipfsMapfileHash', 'processGravatar', Value.fromString('Gravatar'), ['json'])  assert.entityCount(GRAVATAR_ENTITY_TYPE, 3)  assert.fieldEquals(GRAVATAR_ENTITY_TYPE, '1', 'displayName', 'Gravatar1')  assert.fieldEquals(GRAVATAR_ENTITY_TYPE, '2', 'displayName', 'Gravatar2')  assert.fieldEquals(GRAVATAR_ENTITY_TYPE, '3', 'displayName', 'Gravatar3')})

utils.ts file:

import { Address, ethereum, JSONValue, Value, ipfs, json, Bytes } from "@graphprotocol/graph-ts"import { Gravatar } from "../../generated/schema"...// ipfs.map callbackexport function processGravatar(value: JSONValue, userData: Value): void {  // See the JSONValue documentation for details on dealing  // with JSON values  let obj = value.toObject()  let id = obj.get('id')  if (!id) {    return  }  // Callbacks can also created entities  let gravatar = new Gravatar(id.toString())  gravatar.displayName = userData.toString() + id.toString()  gravatar.save()}// function that calls ipfs.catexport function gravatarFromIpfs(): void {  let rawData = ipfs.cat("ipfsCatfileHash")  if (!rawData) {    return  }  let jsonData = json.fromBytes(rawData as Bytes).toObject()  let id = jsonData.get('id')  let url = jsonData.get("imageUrl")  if (!id || !url) {    return  }  let gravatar = new Gravatar(id.toString())  gravatar.imageUrl = url.toString()  gravatar.save()}

断定存储的状态

用户能够通过断定实体断定存储的最终（或中途）状态。为此，用户必须提供实体类型、实体的特定ID、该实体上的字段名称以及字段的预期值。下面是一个快速示例：

import { assert } from 'matchstick-as/assembly/index'import { Gravatar } from '../generated/schema'let gravatar = new Gravatar('gravatarId0')gravatar.save()assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0')

正在运行assert.fieldEquals() 函数将检查给定字段的均等性与给定的预期值。 测试将失败，如果值为 NOT 则输出错误消息。否则测试将成功通过。

与事件元数据交互

用户可以使用 newMockEvent() 函数返回默认的交易元数据。事件可以使用 newMockEvent() 函数。 下面的示例显示您如何在事件对象上读/写到那些字段：

// Readlet logType = newGravatarEvent.logType// Writelet UPDATED_ADDRESS = '0xB16081F360e3847006dB660bae1c6d1b2e17eC2A'newGravatarEvent.address = Address.fromString(UPDATED_ADDRESS)

断定变量相等

assert.equals(ethereum.Value.fromString("hello"); ethereum.Value.fromString("hello"));

断定实体不在存储中

用户可以断定实体在存储中不存在。该函数接受实体类型和id。如果实体实际上在存储中，测试将失败，并显示相关错误消息。以下是如何使用此功能的快速示例：

assert.notInStore('Gravatar', '23')

打印整个内存或单个实体(用于调试目的)

您可以使用此助手功能将整个存储登载到控制台：

import { logStore } from 'matchstick-as/assembly/store'logStore()

从 0.6.0版本 logStore 不再打印派生字段，而是用户可以使用新的 logEntity 函数。 当然，logEntity可以用于打印任何实体，而不仅仅是有衍生字段的实体。 logEntity 需要实体类型、实体ID和一个showRelated标志来表示用户是否想打印相关派生实体。

import { logEntity } from 'matchstick-as/assembly/store'logEntity("Gravatar", 23, true)

预期故障

使用test（）函数上的shouldFail标志，用户可能会出现预期的测试失败：

test(  'Should throw an error',  () => {    throw new Error()  },  true,)

如果测试标记为should fail=true但不失败，则将在日志中显示为错误，测试区块将失败。此外，如果标记为shouldFail=false（默认状态），测试执行器将崩溃。

日志

在单元测试中记录自定义日志与在映射中记录完全相同。不同之处在于，日志对象需要从matchstick-as 而不是graph-ts导入。下面是一个所有非关键日志类型的简单示例：

import { test } from "matchstick-as/assembly/index";import { log } from "matchstick-as/assembly/log";test("Success", () => {    log.success("Success!". []);});test("Error", () => {    log.error("Error :( ", []);});test("Debug", () => {    log.debug("Debugging...", []);});test("Info", () => {    log.info("Info!", []);});test("Warning", () => {    log.warning("Warning!", []);});

用户还可以模拟严重故障，如下所示：

test('Blow everything up', () => {  log.critical('Boom!')})

记录关键错误将停止测试的执行，并使一切崩溃。毕竟，我们希望确保您的代码在部署中没有关键日志，如果发生这种情况，您应该立即注意。

测试派生字段

测试派生字段是一个功能，用户可以在某个实体上设置一个字段，如果它从第一个实体中获得一个字段，则另一个实体会自动更新。

在版本 0.6.0 之前，可以通过以实体字段/属性访问它们来获取派生实体，就像这样：

let entity = ExampleEntity.load('id')let derivedEntity = entity.derived_entity

截至版本0.6'。 , 通过使用graph节点的 loadRelated 函数来做到这一点, 派生的实体可以以与处理器相同的方式访问。

test('Derived fields example test', () => {  let mainAccount = GraphAccount.load('12')!  assert.assertNull(mainAccount.get('nameSignalTransactions'))  assert.assertNull(mainAccount.get('operatorOf'))  let operatedAccount = GraphAccount.load('1')!  operatedAccount.operators = [mainAccount.id]  operatedAccount.save()  mockNameSignalTransaction('1234', mainAccount.id)  mockNameSignalTransaction('2', mainAccount.id)  mainAccount = GraphAccount.load('12')!  assert.assertNull(mainAccount.get('nameSignalTransactions'))  assert.assertNull(mainAccount.get('operatorOf'))  const nameSignalTransactions = mainAccount.nameSignalTransactions.load()  const operatorsOfMainAccount = mainAccount.operatorOf.load()  assert.i32Equals(2, nameSignalTransactions.length)  assert.i32Equals(1, operatorsOfMainAccount.length)  assert.stringEquals('1', operatorsOfMainAccount[0].id)  mockNameSignalTransaction('2345', mainAccount.id)  let nst = NameSignalTransaction.load('1234')!  nst.signer = '11'  nst.save()  store.remove('NameSignalTransaction', '2')  mainAccount = GraphAccount.load('12')!  assert.i32Equals(1, mainAccount.nameSignalTransactions.load().length)})

测试 loadInBlock

从版本 0.6.0 开始，用户可以使用 mockInBlockStore 测试loadInBlock ，它允许在区块缓存中模拟实体。

import { afterAll, beforeAll, describe, mockInBlockStore, test } from 'matchstick-as'import { Gravatar } from '../../generated/schema'describe('loadInBlock', () => {  beforeAll(() => {    mockInBlockStore('Gravatar', 'gravatarId0', gravatar)  })  afterAll(() => {    clearInBlockStore()  })  test('Can use entity.loadInBlock() to retrieve entity from cache store in the current block', () => {    let retrievedGravatar = Gravatar.loadInBlock('gravatarId0')    assert.stringEquals('gravatarId0', retrievedGravatar!.get('id')!.toString())  })  test("Returns null when calling entity.loadInBlock() if an entity doesn't exist in the current block", () => {    let retrievedGravatar = Gravatar.loadInBlock('IDoNotExist')    assert.assertNull(retrievedGravatar)  })})

测试动态数据源

可以通过模拟数据源命名空间的context()、address()和network()的返回值来测试动态数据源。 这些函数目前返回以下内容：context() - 返回一个空实体(DataSourceContext)、address() - 返回 0x000000000000000000000000、net() - 返回 mainnet 。 create(...) 和 createWidext(...) 两个函数都被嘲讽，完全不需要在测试中调用。 对返回值的更改可以通过matchstick-as中的dataSourceMock命名空间的函数进行(版本 0.3.0+)。

示例如下：

首先，我们有以下事件处理程序（它被有意地重新用于展示模拟数据源）：

export function handleApproveTokenDestinations(event: ApproveTokenDestinations): void {  let tokenLockWallet = TokenLockWallet.load(dataSource.address().toHexString())!  if (dataSource.network() == 'rinkeby') {    tokenLockWallet.tokenDestinationsApproved = true  }  let context = dataSource.context()  if (context.get('contextVal')!.toI32() > 0) {    tokenLockWallet.setBigInt('tokensReleased', BigInt.fromI32(context.get('contextVal')!.toI32()))  }  tokenLockWallet.save()}

然后，我们使用dataSourceMock命名空间中的一个方法进行测试，为所有dataSource函数设置一个新返回值：

import { assert, test, newMockEvent, dataSourceMock } from 'matchstick-as/assembly/index'import { BigInt, DataSourceContext, Value } from '@graphprotocol/graph-ts'import { handleApproveTokenDestinations } from '../../src/token-lock-wallet'import { ApproveTokenDestinations } from '../../generated/templates/GraphTokenLockWallet/GraphTokenLockWallet'import { TokenLockWallet } from '../../generated/schema'test('Data source simple mocking example', () => {  let addressString = '0xA16081F360e3847006dB660bae1c6d1b2e17eC2A'  let address = Address.fromString(addressString)  let wallet = new TokenLockWallet(address.toHexString())  wallet.save()  let context = new DataSourceContext()  context.set('contextVal', Value.fromI32(325))  dataSourceMock.setReturnValues(addressString, 'rinkeby', context)  let event = changetype<ApproveTokenDestinations>(newMockEvent())  assert.assertTrue(!wallet.tokenDestinationsApproved)  handleApproveTokenDestinations(event)  wallet = TokenLockWallet.load(address.toHexString())!  assert.assertTrue(wallet.tokenDestinationsApproved)  assert.bigIntEquals(wallet.tokensReleased, BigInt.fromI32(325))  dataSourceMock.resetValues()})

注意，dataSourceMock.resetValues（）在末尾被调用。这是因为值在更改时会被记住，如果要返回到默认值，则需要重新设置。

测试动态数据源创建

从版本 0.6.0 开始，可以测试是否从模板创建了一个新的数据源。 此功能支持etherum/contract 和 file/ipfs 模板。为此有四个函数：

  • assert.dataSourceCount(templateName，expectedCount) 可以用来确定指定模板中的数据源的预期数量
  • assert. ataSourceExists(templateName) address/ipfsHash)声称，从一个指定的模板创建了带有指定标识符的数据源(可以是合约地址或IPFS 文件哈希)
  • logDataSources(templateName) 将指定模板中的所有数据源打印到控制台以进行调试
  • readFile(path) 读取一个 JSON 文件，表示一个 IPFS 文件，并返回内容为字节

测试etherum/contract模板

test('ethereum/contract dataSource creation example', () => {  // Assert there are no dataSources created from GraphTokenLockWallet template  assert.dataSourceCount('GraphTokenLockWallet', 0)  // Create a new GraphTokenLockWallet datasource with address 0xA16081F360e3847006dB660bae1c6d1b2e17eC2A  GraphTokenLockWallet.create(Address.fromString('0xA16081F360e3847006dB660bae1c6d1b2e17eC2A'))  // Assert the dataSource has been created  assert.dataSourceCount('GraphTokenLockWallet', 1)  // Add a second dataSource with context  let context = new DataSourceContext()  context.set('contextVal', Value.fromI32(325))  GraphTokenLockWallet.createWithContext(Address.fromString('0xA16081F360e3847006dB660bae1c6d1b2e17eC2B'), context)  // Assert there are now 2 dataSources  assert.dataSourceCount('GraphTokenLockWallet', 2)  // Assert that a dataSource with address "0xA16081F360e3847006dB660bae1c6d1b2e17eC2B" was created  // Keep in mind that `Address` type is transformed to lower case when decoded, so you have to pass the address as all lower case when asserting if it exists  assert.dataSourceExists('GraphTokenLockWallet', '0xA16081F360e3847006dB660bae1c6d1b2e17eC2B'.toLowerCase())  logDataSources('GraphTokenLockWallet')})
示例 logDataSource 输出
🛠  {  "0xa16081f360e3847006db660bae1c6d1b2e17ec2a": {    "kind": "ethereum/contract",    "name": "GraphTokenLockWallet",    "address": "0xa16081f360e3847006db660bae1c6d1b2e17ec2a",    "context": null  },  "0xa16081f360e3847006db660bae1c6d1b2e17ec2b": {    "kind": "ethereum/contract",    "name": "GraphTokenLockWallet",    "address": "0xa16081f360e3847006db660bae1c6d1b2e17ec2b",    "context": {      "contextVal": {        "type": "Int",        "data": 325      }    }  }}

测试file/ipfs模板

类似于合约动态数据源，用户可以测试文件数据源及其处理程序

示例 subgraph.yaml
...templates: - kind: file/ipfs    name: GraphTokenLockMetadata    network: mainnet    mapping:      kind: ethereum/events      apiVersion: 0.0.9      language: wasm/assemblyscript      file: ./src/token-lock-wallet.ts      handler: handleMetadata      entities:        - TokenLockMetadata      abis:        - name: GraphTokenLockWallet          file: ./abis/GraphTokenLockWallet.json
示例 schema.graphql
"""Token Lock Wallets which hold locked GRT"""type TokenLockMetadata @entity {  "The address of the token lock wallet"  id: ID!  "Start time of the release schedule"  startTime: BigInt!  "End time of the release schedule"  endTime: BigInt!  "Number of periods between start time and end time"  periods: BigInt!  "Time when the releases start"  releaseStartTime: BigInt!}
示例 metadata.json
{  "startTime": 1,  "endTime": 1,  "periods": 1,  "releaseStartTime": 1}
示例处理程序：
export function handleMetadata(content: Bytes): void {  // dataSource.stringParams() returns the File DataSource CID  // stringParam() will be mocked in the handler test  // for more info https://thegraph.com/docs/en/developing/creating-a-subgraph/#create-a-new-handler-to-process-files  let tokenMetadata = new TokenLockMetadata(dataSource.stringParam())  const value = json.fromBytes(content).toObject()  if (value) {    const startTime = value.get('startTime')    const endTime = value.get('endTime')    const periods = value.get('periods')    const releaseStartTime = value.get('releaseStartTime')    if (startTime && endTime && periods && releaseStartTime) {      tokenMetadata.startTime = startTime.toBigInt()      tokenMetadata.endTime = endTime.toBigInt()      tokenMetadata.periods = periods.toBigInt()      tokenMetadata.releaseStartTime = releaseStartTime.toBigInt()    }    tokenMetadata.save()  }}
Example test
import { assert, test, dataSourceMock, readFile } from 'matchstick-as'import { Address, BigInt, Bytes, DataSourceContext, ipfs, json, store, Value } from '@graphprotocol/graph-ts'import { handleMetadata } from '../../src/token-lock-wallet'import { TokenLockMetadata } from '../../generated/schema'import { GraphTokenLockMetadata } from '../../generated/templates'test('file/ipfs dataSource creation example', () => {  // Generate the dataSource CID from the ipfsHash + ipfs path file  // For example QmaXzZhcYnsisuue5WRdQDH6FDvqkLQX1NckLqBYeYYEfm/example.json  const ipfshash = 'QmaXzZhcYnsisuue5WRdQDH6FDvqkLQX1NckLqBYeYYEfm'  const CID = `${ipfshash}/example.json`  // Create a new dataSource using the generated CID  GraphTokenLockMetadata.create(CID)  // Assert the dataSource has been created  assert.dataSourceCount('GraphTokenLockMetadata', 1)  assert.dataSourceExists('GraphTokenLockMetadata', CID)  logDataSources('GraphTokenLockMetadata')  // Now we have to mock the dataSource metadata and specifically dataSource.stringParam()  // dataSource.stringParams actually uses the value of dataSource.address(), so we will mock the address using dataSourceMock from  matchstick-as  // First we will reset the values and then use dataSourceMock.setAddress() to set the CID  dataSourceMock.resetValues()  dataSourceMock.setAddress(CID)  // Now we need to generate the Bytes to pass to the dataSource handler  // For this case we introduced a new function readFile, that reads a local json and returns the content as Bytes  const content = readFile(`path/to/metadata.json`)  handleMetadata(content)  // Now we will test if a TokenLockMetadata was created  const metadata = TokenLockMetadata.load(CID)  assert.bigIntEquals(metadata!.endTime, BigInt.fromI32(1))  assert.bigIntEquals(metadata!.periods, BigInt.fromI32(1))  assert.bigIntEquals(metadata!.releaseStartTime, BigInt.fromI32(1))  assert.bigIntEquals(metadata!.startTime, BigInt.fromI32(1))})

测试覆盖率

使用Matchstick，子图开发者可以运行一个脚本，计算编写的单元测试的测试覆盖率。

测试覆盖工具接受已编译的测试 wasm 二进制并将它们转换为 wat 文件， 然后便于检查，看看是否subgraph.yaml中定义的处理程序已被调用。 因为代码覆盖面(和整个测试)在 AssemblyScript 和 WebAssembly 中处于早期阶段，Matchstick 无法检查分支覆盖面。 相反，我们依赖的是这样一种说法：如果一个处理程序被调用了，它的事件/功能就被恰当地仿效了。

先决条件

要运行在 Matchstick* 中提供的测试覆盖功能，您需要事先准备几件事：

导出处理程序

为了让Matchstick 检查哪些处理程序正在运行，这些处理程序需要从 测试文件 导出。 因此，例如在我们的例子中，在我们的gravity.test.ts文件中，我们有以下处理程序被导入：

import { handleNewGravatar } from '../../src/gravity'

为了让这个函数可见，我们也需要导出它(以名字写入wat文件)。 像这样：

export { handleNewGravatar }

使用方法

设置好后，要运行测试覆盖工具，只需运行：

graph test -- -c

你也可以在你的 package.json 文件中添加一个自定义的 coverage 命令，就像这样：

"scripts": {    /.../    "coverage": "graph test -- -c"  },

希望这可以毫无问题地执行覆盖工具。您应该在终端中看到类似的内容：

$ graph test -cSkipping download/install step because binary already exists at /Users/petko/work/demo-subgraph/node_modules/binary-install-raw/bin/0.4.0___  ___      _       _         _   _      _|  \/  |     | |     | |       | | (_)    | || .  . | __ _| |_ ___| |__  ___| |_ _  ___| | __| |\/| |/ _` | __/ __| '_ \/ __| __| |/ __| |/ /| |  | | (_| | || (__| | | \__ \ |_| | (__|   <\_|  |_/\__,_|\__\___|_| |_|___/\__|_|\___|_|\_\Compiling...Running in coverage report mode. ️Reading generated test modules... 🔎️Generating coverage report 📝Handlers for source 'Gravity':Handler 'handleNewGravatar' is tested.Handler 'handleUpdatedGravatar' is not tested.Handler 'handleCreateGravatar' is tested.Test coverage: 66.7% (2/3 handlers).Handlers for source 'GraphTokenLockWallet':Handler 'handleTokensReleased' is not tested.Handler 'handleTokensWithdrawn' is not tested.Handler 'handleTokensRevoked' is not tested.Handler 'handleManagerUpdated' is not tested.Handler 'handleApproveTokenDestinations' is not tested.Handler 'handleRevokeTokenDestinations' is not tested.Test coverage: 0.0% (0/6 handlers).Global test coverage: 22.2% (2/9 handlers).

日志输出中的测试运行持续时间

日志输出包括测试运行持续时间。下面是一个示例：

常见编译器错误

关键：无法从具有背景的有效模块创建WasmInstance：未知导入：wasi_snapshot_preview1:：尚未定义fd_write

这意味着您在代码中使用了console.log，不被 AssemblyScript 支持。请考虑使用 日志API。

ERROR TS2554: Expected ? arguments, but got ?.

返回ethereum.Block(defaultAddressBytes, defaultAddressBytes, defaultAddressBytes, defaultAddress, defaultAddressBytes, defaultAddressBytes, defaultAddressBytes, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt, defaultBigInt);

in ~lib/matchstick-as/assembly/defaults.ts(18,12)

ERROR TS2554: Expected ? arguments, but got ?.

返回新ethereum.Transaction(defaultAddressBytes, defaultBigInt, defaultAddress, defaultAddress, defaultBigInt, defaultBigInt, defaultBigInt, defaultAddressBytes, defaultBigInt);

in ~lib/matchstick-as/assembly/defaults.ts(24,12)

参数中的不匹配是由graph-ts和matchstick-as中的不匹配造成的。 解决这类问题的最佳方法是更新最新发布的版本。

其他资源

如需任何额外支持，请查看此使用Matchstick的演示子图仓库⁠。

反馈

如果您有任何问题、反馈、特征请求或只是想与我们联系，最好的地方是 Graph Discord，我们有一个专门的 Matchstick 频道，名为 🔥| 单元测试。