Docs
⌘ K

25 dakika

Birim Testi Framework'ü

Learn how to use Matchstick, a unit testing framework developed by LimeChain⁠. Matchstick enables Subgraph developers to test their mapping logic in a sandboxed environment and successfully deploy their Subgraphs.

Benefits of Using Matchstick

  • It’s written in Rust and optimized for high performance.
  • It gives you access to developer features, including the ability to mock contract calls, make assertions about the store state, monitor Subgraph failures, check test performance, and many more.

Buradan Başlayın

Install Dependencies

In order to use the test helper methods and run tests, you need to install the following dependencies:

yarn add --dev matchstick-as

Install PostgreSQL

graph-node depends on PostgreSQL, so if you don’t already have it, then you will need to install it.

Note: It’s highly recommended to use the commands below to avoid unexpected errors.

Using MacOS

Installation command:

brew install postgresql

Create a symlink to the latest libpq.5.lib You may need to create this dir first /usr/local/opt/postgresql/lib/

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

Using Linux

Installation command (depends on your distro):

sudo apt install postgresql

Using WSL (Windows Subsystem for Linux)

Matchstick’i WSL’de Docker yaklaşımı ve ikili yaklaşımı kullanarak kullanabilirsiniz. WSL biraz alengirli olabileceğinden, aşağıdaki gibi sorunlarla karşılaşırsanız birkaç ipucu verelim

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

yada

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

Please make sure you’re on a newer version of Node.js graph-cli doesn’t support v10.19.0 anymore, and that is still the default version for new Ubuntu images on WSL. For instance Matchstick is confirmed to be working on WSL with v18.1.0, you can switch to it either via nvm or if you update your global Node.js. Don’t forget to delete node_modules and to run npm install again after updating you nodejs! Then, make sure you have libpq installed, you can do that by running

sudo apt-get install libpq-dev

And finally, do not use graph test (which uses your global installation of graph-cli and for some reason that looks like it’s broken on WSL currently), instead use yarn test or npm run test (that will use the local, project-level instance of graph-cli, which works like a charm). For that you would of course need to have a "test" script in your package.json file which can be something as simple as

{  "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"  }}

Using Matchstick

To use Matchstick in your Subgraph project just open up a terminal, navigate to the root folder of your project and simply run graph test [options] <datasource> - it downloads the latest Matchstick binary and runs the specified test or all tests in a test folder (or all existing tests if no datasource flag is specified).

CLI seçenekleri

Bu, test klasöründeki tüm testleri çalıştıracaktır:

graph test

Bu, gravity.test.ts adında bir testi ve/veya gravity adında bir klasördeki tüm testleri çalıştıracaktır:

graph test gravity

Bu sadece belirtilen test dosyasını çalıştıracaktır:

graph test path/to/file.test.ts

Options:

-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

From graph-cli 0.25.2, the graph test command supports running matchstick in a docker container with the -d flag. The docker implementation uses bind mount⁠ so it does not have to rebuild the docker image every time the graph test -d command is executed. Alternatively you can follow the instructions from the matchstick⁠ repository to run docker manually.

❗ graph test -d forces docker run to run with flag -t. This must be removed to run inside non-interactive environments (like GitHub CI).

❗ If you have previously ran graph test you may encounter the following error during docker build:

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

In this case create a .dockerignore in the root folder and add node_modules/binary-install-raw/bin

Yapılandırma

Matchstick can be configured to use a custom tests, libs and manifest path via matchstick.yaml config file:

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

Demo Subgraph

You can try out and play around with the examples from this guide by cloning the Demo Subgraph repo⁠

Öğretici videolar

Also you can check out the video series on “How to use Matchstick to write unit tests for your Subgraphs”⁠

Test yapısı

IMPORTANT: The test structure described below depends on matchstick-as version >=0.5.0

describe()

describe(name: String , () => {}) - Defines a test group.

Notes:

  • Açıklamalar zorunlu değildir. Hala test() fonksiyonunu describe() bloklarının dışında kullanabilirsiniz

Örnek:

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

Nested describe() example:

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()

test(name: String, () =>, should_fail: bool) - Defines a test case. You can use test() inside of describe() blocks or independently.

Örnek:

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

yada

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

beforeAll()

Runs a code block before any of the tests in the file. If beforeAll is declared inside of a describe block, it runs at the beginning of that describe block.

Örnekler:

Code inside beforeAll will execute once before all tests in the file.

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", () => {    ...  })})

Code inside beforeAll will execute once before all tests in the first describe block

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()

Runs a code block after all of the tests in the file. If afterAll is declared inside of a describe block, it runs at the end of that describe block.

Örnek:

Code inside afterAll will execute once after all tests in the file.

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", () => {    ...  })})

Code inside afterAll will execute once after all tests in the first describe block

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()

Runs a code block before every test. If beforeEach is declared inside of a describe block, it runs before each test in that describe block.

Examples: Code inside beforeEach will execute before each tests.

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", () => {    ...  })}) ...

Code inside beforeEach will execute only before each test in the that describe

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()

Runs a code block after every test. If afterEach is declared inside of a describe block, it runs after each test in that describe block.

Örnekler:

Code inside afterEach will execute after every test.

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")  })})

Code inside afterEach will execute after each test in that describe

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")  })})

Açıklamalar

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)

Sürüm 0.6.0 itibariyle, assert fonksiyonları özel hata mesajlarını da desteklemektedir

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',)

Bir Birim Testi Yazın

Let’s see how a simple unit test would look like using the Gravatar examples in the Demo Subgraph⁠.

Aşağıdaki işleyici fonksiyonuna sahip olduğumuzu varsayarsak (iki yardımcı işlevle birlikte):

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}

Önce projemizde bir test dosyası oluşturmamız gerekiyor. Bunun nasıl görünebileceğine dair bir örnek:

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', () => {  //...})

That’s a lot to unpack! First off, an important thing to notice is that we’re importing things from matchstick-as, our AssemblyScript helper library (distributed as an npm module). You can find the repository here⁠. matchstick-as provides us with useful testing methods and also defines the test() function which we will use to build our test blocks. The rest of it is pretty straightforward - here’s what happens:

  • İlk durumumuzu ayarlıyor ve bir özel Gravatar varlığı ekliyoruz;
  • We define two NewGravatar event objects along with their data, using the createNewGravatarEvent() function;
  • We’re calling out handler methods for those events - handleNewGravatars() and passing in the list of our custom events;
  • Depo durumunu doğruluyoruz. Bu nasıl çalışır? - Bir varlık türü ve kimliğinin benzersiz bir kombinasyonunu geçiriyoruz. Ardından, bu varlıkta belirli bir alanı kontrol ediyoruz ve beklediğimiz değeri almasını sağlıyoruz. Hem depoya eklediğimiz ilk Gravatar Varlığı için hem de işleyici işlevi çağrıldığında eklenen iki Gravatar varlığı için bunu yapıyoruz;
  • And lastly - we’re cleaning the store using clearStore() so that our next test can start with a fresh and empty store object. We can define as many test blocks as we want.

İşte başardın - ilk testimizi oluşturduk! 👏

Now in order to run our tests you simply need to run the following in your Subgraph root folder:

graph test Gravity

Ve her şey yolunda giderse aşağıdakiyle karşılaşacaksınız:

Matchstick saying “All tests passed!”

Çok rastlanan test senaryoları

Belirli bir durumla depoyu doldurma

Kullanıcılar bilinen bir varlık kümesiyle depoyu doldurabilirler. Aşağıdaki örnek depoyu Gravatar varlığıyla başlatmak için kullanılabilir:

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

Olayla bir eşleştirme fonksiyonu çağırmak

Kullanıcı, depoya bağlı bir eşleştirme fonksiyonuna özel bir olay oluşturabilir ve onu iletebilir:

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)

Tüm eşitlemeleri olay fikstürleriyle çağırmak

Kullanıcılar test fikstürleriyle eşleştirmeleri çağırabilirler.

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);    });}

Kontrat çağrılarını mocklama

Kullanıcılar sözleşme çağrılarını mocklayabilir:

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))

Gösterildiği gibi, bir sözleşme çağrısını mocklamak ve bir dönüş değeri sabitlemek için kullanıcı, bir sözleşme adresi, işlev adı, işlev imzası, bir argüman dizisi ve elbette dönüş değerini sağlamalıdır.

Kullanıcılar ayrıca fonksiyon geri çevirilerinide mocklayabilirler:

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

IPFS dosyalarını mocklama (Matchstick 0.4.1’den)

Users can mock IPFS files by using mockIpfsFile(hash, filePath) function. The function accepts two arguments, the first one is the IPFS file hash/path and the second one is the path to a local file.

NOTE: When testing ipfs.map/ipfs.mapJSON, the callback function must be exported from the test file in order for matchstick to detect it, like the processGravatar() function in the test example bellow:

.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 geri çağrısıexport function processGravatar(value: JSONValue, userData: Value): void {  // İşlem yapmayla ilgili ayrıntılar için JSONValue belgelerine bakın  // JSON değerleri ile  let obj = value.toObject()  let id = obj.get('id')  if (!id) {    return  }  // Geri çağrılar ayrıca varlıklar oluşturabilir  let gravatar = new Gravatar(id.toString())  gravatar.displayName = userData.toString() + id.toString()  gravatar.save()}// ipfs.cat'i çağıran fonksiyonexport 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()}

Depo durumunu doğrulama

Kullanıcılar, varlıkları doğrulayarak deponun nihai (veya orta) durumunu doğrulayabilirler. Bunun için, kullanıcı bir Varlık türü, bir Varlığın belirli bir kimliği, o Varlıktaki bir alanın adı ve alanın beklenen değerini sağlamalıdır. Hızlıca bir örneğe bakalım:

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')

Running the assert.fieldEquals() function will check for equality of the given field against the given expected value. The test will fail and an error message will be outputted if the values are NOT equal. Otherwise the test will pass successfully.

Olay üst verileriyle etkileşim

Users can use default transaction metadata, which could be returned as an ethereum.Event by using the newMockEvent() function. The following example shows how you can read/write to those fields on the Event object:

// Okumalet logType = newGravatarEvent.logType// Yazmalet UPDATED_ADDRESS = '0xB16081F360e3847006dB660bae1c6d1b2e17eC2A'newGravatarEvent.address = Address.fromString(UPDATED_ADDRESS)

Değişken eşitliğini doğrulama

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

Asserting that an Entity is not in the store

Kullanıcılar, bir varlığın depoda olmadığını doğrulayabilirler. Bu fonksiyon, bir varlık türü ve bir kimlik alır. Eğer varlık gerçekten depoda ise, test ilgili bir hata mesajı vererej başarısız olacaktır. Fonksiyonun nasıl kullanılacağına dair hızlıca bir örneğe bakalım:

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

Tüm mağazayı veya tüm mağazadan tek varlıkları yazdırma (hata ayıklama amaçlı)

Bu yardımcı fonksiyon kullanılarak deponun tamamı konsola yazdırılabilir:

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

As of version 0.6.0, logStore no longer prints derived fields, instead users can use the new logEntity function. Of course logEntity can be used to print any entity, not just ones that have derived fields. logEntity takes the entity type, entity id and a showRelated flag to indicate if users want to print the related derived entities.

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

Beklenen başarısızlık

Kullanıcılar, shouldFail bayrağını test() fonksiyonlarında kullanarak beklenen test başarısızlıklarına sahip olabilirler:

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

Test, shouldFail = true olarak işaretlenirse ama BAŞARISIZ olmazsa, bu kayıtlarda bir hata olarak görünecek ve test bloğu başarısız olacaktır. Ayrıca, with shouldFail = false (the default state) olarak işaretlenirse, test yürütücüsü çökecektir.

Kayıt tutma

Birim testlerinde özel kayıt tutmanın eşitlemelerdeki kayıt tutmaktan tamamen aynıdır. Fark, günlük nesnesinin graph-ts yerine matchstick-as’dan içe aktarılması gerektmesidir. İşte tüm kritik olmayan kayıt türleriyle ilgili basit bir örnek:

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!", []);});

Kullanıcılar ayrıca şu şekilde kritik bir hatayı simüle edebilirler:

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

Kritik hataları kayıt altına almak, testlerin yürütülmesini durduracak ve her şeyi mahvedecektir. Sonuçta, kodunuzun dağıtımda kritik kayıtları içermediğinden emin olmak istiyoruz ve bunun olması durumunda hemen fark etmeniz gerekiyor.

Türetilmiş alanların test edilmesi

Türetilmiş alanları test etme özelliği, belirli bir varlıkta bir alan belirleyip, bu varlıktan türetilmiş bir alan içeriyoren başka bir varlığın otomatik olarak güncellenmesini sağlayan bir özelliktir.

Before version 0.6.0 it was possible to get the derived entities by accessing them as entity fields/properties, like so:

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

As of version 0.6.0, this is done by using the loadRelated function of graph-node, the derived entities can be accessed the same way as in the handlers.

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)})

Testing loadInBlock

As of version 0.6.0, users can test loadInBlock by using the mockInBlockStore, it allows mocking entities in the block cache.

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)  })})

Dinamik Veri Kaynaklarının Test Edilmesi

Testing dynamic data sources can be be done by mocking the return value of the context(), address() and network() functions of the dataSource namespace. These functions currently return the following: context() - returns an empty entity (DataSourceContext), address() - returns 0x0000000000000000000000000000000000000000, network() - returns mainnet. The create(...) and createWithContext(...) functions are mocked to do nothing so they don’t need to be called in the tests at all. Changes to the return values can be done through the functions of the dataSourceMock namespace in matchstick-as (version 0.3.0+).

Aşağıdaki örnekte:

Öncelikle aşağıdaki olay işleyicisine sahibiz (veri kaynağı mocklamasını göstermek için kasıtlı olarak amaç değişikliği):

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()}

Ardından, dataSourceMock ad alanındaki yöntemlerden birini kullanarak tüm veri kaynağı fonksiyonları için yeni bir geri dönüş değeri ayarlayan testi görüyoruz:

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()‘in en sonda çağrıldığına dikkat edin. Bunun nedeni değerler değiştirildiğinde hatırlanır ve varsayılan değerlere geri dönmek istiyorsanız sıfırlanmaları gerekir.

Dinamik veri kaynağı oluşturulmasının test edilmesi

As of version 0.6.0, it is possible to test if a new data source has been created from a template. This feature supports both ethereum/contract and file/ipfs templates. There are four functions for this:

  • assert.dataSourceCount(templateName, expectedCount) can be used to assert the expected count of data sources from the specified template
  • assert.dataSourceExists(templateName, address/ipfsHash) asserts that a data source with the specified identifier (could be a contract address or IPFS file hash) from a specified template was created
  • logDataSources(templateName) prints all data sources from the specified template to the console for debugging purposes
  • readFile(path) reads a JSON file that represents an IPFS file and returns the content as Bytes

Testing ethereum/contract templates

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')})
Example logDataSource output
🛠  {  "0xa16081f360e3847006db660bae1c6d1b2e17ec2a": {    "kind": "ethereum/contract",    "name": "GraphTokenLockWallet",    "address": "0xa16081f360e3847006db660bae1c6d1b2e17ec2a",    "context": null  },  "0xa16081f360e3847006db660bae1c6d1b2e17ec2b": {    "kind": "ethereum/contract",    "name": "GraphTokenLockWallet",    "address": "0xa16081f360e3847006db660bae1c6d1b2e17ec2b",    "context": {      "contextVal": {        "type": "Int",        "data": 325      }    }  }}

Testing file/ipfs templates

Similarly to contract dynamic data sources, users can test test file data sources and their handlers

Example 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
Example schema.graphql
"""Kilitli GRT tutan Token Kilit Cüzdanları"""type TokenLockMetadata @entity {  "Token kilit cüzdanının adresi"  id: ID!  "Serbest bırakma programının başlangıç zamanı"  startTime: BigInt!  "Serbest bırakma programının bitiş zamanı"  endTime: BigInt!  "Başlangıç zamanı ile bitiş zamanı arasındaki periyot sayısı"  periods: BigInt!  "Serbest bırakmaların başladığı zaman"  releaseStartTime: BigInt!}
Example metadata.json
{  "startTime": 1,  "endTime": 1,  "periods": 1,  "releaseStartTime": 1}
İşleyici örneği
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()  }}
Test örneği
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))})

Test Kapsamı

Using Matchstick, Subgraph developers are able to run a script that will calculate the test coverage of the written unit tests.

The test coverage tool takes the compiled test wasm binaries and converts them to wat files, which can then be easily inspected to see whether or not the handlers defined in subgraph.yaml have been called. Since code coverage (and testing as whole) is in very early stages in AssemblyScript and WebAssembly, Matchstick cannot check for branch coverage. Instead we rely on the assertion that if a given handler has been called, the event/function for it have been properly mocked.

Prerequisites

To run the test coverage functionality provided in Matchstick, there are a few things you need to prepare beforehand:

İşleyicilerinizi dışa aktarın

In order for Matchstick to check which handlers are being run, those handlers need to be exported from the test file. So for instance in our example, in our gravity.test.ts file we have the following handler being imported:

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

In order for that function to be visible (for it to be included in the wat file by name) we need to also export it, like this:

export { handleNewGravatar }

Usage

Her şey hazır olduğunda, test kapsama aracını çalıştırmak için basitçe şunu çalıştırın:

graph test -- -c

You could also add a custom coverage command to your package.json file, like so:

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

Bu, kapsama aracını çalıştıracak ve terminalde buna benzer bir şey göreceksiniz:

$ 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).

Tutulan kayıt çıktısında test çalışma süresi

Tutulan kayıt çıktısı test çalışma süresini içerir. İşte buna bir örnek:

[Thu, 31 Mar 2022 13:54:54 +0300] Program executed in: 42.270ms.

Çok rastlanan derleyici hataları

Critical: Could not create WasmInstance from valid module with context: unknown import: wasi_snapshot_preview1::fd_write has not been defined

This means you have used console.log in your code, which is not supported by AssemblyScript. Please consider using the Logging API

ERROR TS2554: Expected ? arguments, but got ?.

return new 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 ?.

return new ethereum.Transaction(defaultAddressBytes, defaultBigInt, defaultAddress, defaultAddress, defaultBigInt, defaultBigInt, defaultBigInt, defaultAddressBytes, defaultBigInt);

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

The mismatch in arguments is caused by mismatch in graph-ts and matchstick-as. The best way to fix issues like this one is to update everything to the latest released version.

Ek Kaynaklar

For any additional support, check out this demo Subgraph repo using Matchstick⁠.

Geribildirim

Soru, geri bildirim, özellik istekleri veya sadece iletişim kurmak istiyorsanız en iyi yer Matchstick için ayrılmış bir kanal olan 🔥| unit-testing kanalına sahip olduğumuz The Graph Discord’udur.