使用 JavaScript 为 Cadence 智能合约编写单元测试

使用 JavaScript 为 Cadence 智能合约编写单元测试

本文假设读者熟悉了 Cadence 智能合约的编写，熟悉 Flow 区块链的基础知识，并具备一定的 JavaScript 语言基础。

写在前面

// setup test case
export const setupTest = () =>

describe('Contract setup test cases', () => {

	beforeAll(() => {
		// 在每次用例之前调用 fcl 的配置
		return fclInit()

		dotenv.config()

	})
	// test unit
	test('init admin resource failed', async () => {

		const res = await buildSetupTrx('initFlownsAdminStorage')

		expect(res).toBeNull()

	})

	test('init admin cap with root domain collection', async () => {

		const res = await buildSetupTrx('setupAdminServer', [])

		expect(res).not.toBeNull()

		const { status } = res

		// check trx status
		expect(status).toBe(4)
	})

	// ...

})

• 非托管模式的签名工具不完善

• Cadence 开发环境变量过度依赖 flow.json 配置，也不支持配置扩展

• 脚本文件比较多不好管理，需要动态加载脚本文件完成 Js 的调用

• 环境切换所需要的配置方法和流程不同，需要做自动化处理

测试环境初始化与切换

• 本地环境 - localnet

• 测试环境 - testnet

• 主网环境 - mainnet

flow.json 配置

{
  "emulators": {
    "default": {
      "port": 3569,
      "serviceAccount": "emulator-account"
    }
  },
  "networks": {
    "emulator": "127.0.0.1:3569",
    "mainnet": "access.mainnet.nodes.onflow.org:9000",
    "testnet": "access.devnet.nodes.onflow.org:9000"
  },
  "accounts": {
    "emulator-account": {
      "address": "f8d6e0586b0a20c7",
      "key": "ae1b44c0f5e8f6992ef2348898a35e50a8b0b9684000da8b1dade1b3bcd6ebee",
    }
  },
  "deployments": {}, //
  "contracts": {}  // contracts
}

• networks: 配置不同网络的节点

• accounts: 配置测试环节所需要使用到的账户信息（包含私钥和地址，会有私钥泄露的风险）这里在主网环境中需要谨慎填写，或者使用环境变量替代（后面会讲到）

• deployments: 配置合约所需要部署的账户关系。

• contracts: 配置合约关联关系

dotenv

• access node 地址

• 管理员地址与私钥

• 依赖合约的地址

• 开发平台或第三方平台的 apiKey 等等

FLOW_ACCOUNT_ADDRESS=0xb05b2abb42335e88
FLOW_ACCOUNT_KEY_ID=0
FLOW_ACCOUNT_PRIVATE_KEY=<key>
FLOW_ACCOUNT_PUBLIC_KEY=acec1c454....1656a4d4cc592e6f
FLOW_TOKEN_ADDRESS=0x7e60df042a9c0868
FUSD_TOKEN_ADDRESS=0xe223d8a629e49c68
FLOW_FUNGIBLE_ADDRESS=0x9a0766d93b6608b7
FLOW_NONFUNGIBLE_ADDRESS=0x631e88ae7f1d7c20
ALCHEMY_KEY=jzmz.....laqhxy9r

import dotenv from 'dotenv'

dotenv.config()

export const nodeUrl = process.env.FLOW_ACCESS_NODE

export const privateKey = process.env.FLOW_ACCOUNT_PRIVATE_KEY

export const accountKeyId = process.env.FLOW_ACCOUNT_KEY_ID

export const accountAddr = process.env.FLOW_ACCOUNT_ADDRESS

export const flowTokenAddr = process.env.FLOW_TOKEN_ADDRESS

export const FUSDTokenAddr = process.env.FUSD_TOKEN_ADDRESS

export const KibbleTokenAddr = process.env.KIBBLE_TOKEN_ADDRESS

export const flowFungibleAddr = process.env.FLOW_FUNGIBLE_ADDRESS

export const flowNonFungibleAddr = process.env.FLOW_NONFUNGIBLE_ADDRESS

export const publicKey = process.env.FLOW_ACCOUNT_PUBLIC_KEY

export const alchemyKey = process.env.ALCHEMY_KEY

export const fclInit = () => {

fcl.config()
.put('accessNode.api', nodeUrl)
.put('0xDomains', accountAddr)
.put('0xFlowns', accountAddr)
.put('0xNonFungibleToken', flowNonFungibleAddr)
.put('0xFungibleToken', flowFungibleAddr)
.put('0xFlowToken', flowTokenAddr)
.put("grpc.metadata", {"api_key": alchemyKey})
}

配置调用初始化命令

• 本地多账户创建

• 合约部署

• 测试脚本整合

• 自定义脚本配置

{

	"scripts": {
		//...
		"test": "node --experimental-vm-modules node_modules/.bin/jest",
		"setup:env": "node scripts/setupEnv.js",
		"init:emulator": "flow project deploy && yarn acc:test1 && yarn acc:test2 && yarn setup:env ",
		"acc:test1": "flow accounts create --key 05013fc02bde69176dd7668422e834411bd38189ffe5db4c63083c39de75cc61b850929065b6a68411653a1790183c99012077761335d5ecd4a70a89d4bc2627",
		"acc:test2": "flow accounts create --key d44419da1d05f4d448e48501dfa1069513b71de08b57904e7599369296754dc42da4207edc561f5fd47c06b677d9d3cdf18274d3911201f02a019f96510f1572",
		"setup:testnet": "node scripts/setupTestnetContract.js"

	}
}

• acc:test1 : 在模拟器中生成测试账户1

• acc:test2: 在模拟器中生成测试账户2

• setup:env: 根据账户配置初始化账户余额和一些测试需要的参数

注意: 因为在本地环境相同的 key 创建出来的账户地址始终相同，那么我们可以将测试多账户的对应的地址进行变量配置。

用 JavaScript 实现私钥签名

// local

export const test1Addr = '0x01cf0e2f2f715450'
export const test2Addr = '0x179b6b1cb6755e31'

export function authFunc(opt = {}) {

	const { addr, keyId = 0, tempId = 'SERVICE_ACCOUNT', key } = opt
	return (account) => {
		return {
			...account,
			tempId,
			addr: fcl.sansPrefix(addr),
			keyId: Number(keyId),
			signingFunction: (signable) => ({
			addr: fcl.withPrefix(addr), // must match the address that requested the signature, but with a prefix
			keyId: Number(keyId), // must match the keyId in the account that requested the signature
			signature: sign(key, signable.message), // signable.message |> hexToBinArray |> hash |> sign |> binArrayToHex
			}),
		}
	}
}



export function test1Authz() {

	const authz = authFunc({

		addr: test1Addr,

		key: '368083923398158...cc173dbd5c78b6b4',

		keyId: 0,

	})

	return authz

}



export function test2Authz() {

	const authz = authFunc({

		addr: test2Addr,

		key: '5f10a1fd823...238688967',

		keyId: 0,

	})

return authz

}

这里为了安全起见，也可以将 key 参数配置在环境变量里，因为这里只用在本地和测试环境，就不做单独处理。

Cadence 查询与交易脚本管理

const buildPath = (fileName, type) => {

let filePath = ''

switch (type) {

	case 'setup':
		filePath = `../cadence/transactions/setup/${fileName}`
		break
	case 'script':
		filePath = `../cadence/scripts/${fileName}`
		break
	default:
		filePath = `../cadence/transactions/${fileName}`

	}

	return filePath

}

export const paths = {

setup: {

	initDomainCollection: buildPath('init_domains_collection.cdc', 'setup'),

	initFlownsAdminStorage: buildPath('init_flowns_admin_storage.cdc', 'setup'),
	//...
},

scripts: {

	checkDomainCollection: buildPath('check_domain_collection.cdc', 'script'),

	checkFlownsAdmin: buildPath('check_flowns_admin.cdc', 'script'),
	//...
},

transactions: {

	registerDomain: buildPath('register_domain.cdc'),

	registerDomainBatch: buildPath('register_domain_batch.cdc'),
	//...
	},

}

// 支持传入自定义的签名函数，执行交易脚本
export const buildAndSendTrx = async (key, args = [], authFunc = null, limit=9999) => {

	try {
		// 读取对应的脚本内容
		const trxScript = await readCode(transactions[key])

		const trxId = await sendTrx(trxScript, args, authFunc, limit)

		const txStatus = await fcl.tx(trxId).onceSealed()

		return txStatus

	} catch (error) {

		console.log(error)

	return null

	}

}



export const sendTrx = async (CODE, args, auth = null, limit = 9999) => {

	const authFunc = auth || authz

	const txId = await fcl.send([
			fcl.transaction(CODE),
			fcl.args(args),
			fcl.proposer(authFunc),
			fcl.payer(authFunc),
			fcl.authorizations([authFunc]),
			fcl.limit(limit),
		]).then(fcl.decode)

	return txId

}

export const buildAndExecScript = async (key, args = []) => {
	// 读取映射中的 script 脚本内容
	const script = await readCode(scripts[key])

	const result = await execScript(script, args)

	return result

}

export const readCode = async (path) => {

	const data = fs.readFileSync(resolve(__dirname, path), 'utf-8')

	return data

}

export const sleep = async (time) => {

	return new Promise((resolve) => setTimeout(resolve, time))

}

// 查询脚本结果 key 与 buildpath 中的 key 对应
const result = await buildAndExecScript('checkDomainCollection', [

	fcl.arg('0xf8d6e0586b0a20c7', t.Address),

])

// 使用 test1 和 test2 的账户授权初始化账户资源
await buildSetupTrx('initTokens', [], test1Authz())

await buildSetupTrx('initTokens', [], test2Authz())

变量替换

import Domains from 0xDomains

pub fun main(address: Address) : Bool {

	return getAccount(address).getCapability<&{Domains.CollectionPublic}>(Domains.CollectionPublicPath).check()

}

测试用例编写

// 并行变串行

import { setupTest } from './testSuite/setup.js'

import { userTest } from './testSuite/userCase.js'

describe('flowns test case', () => {

	setupTest()

	userTest()

})

// setup test case
export const setupTest = () =>

describe('Contract setup test cases', () => {

	beforeAll(() => {
		// 在每次用例之前调用 fcl 的配置
		return fclInit()

		dotenv.config()

	})
	// test unit
	test('init admin resource failed', async () => {

		const res = await buildSetupTrx('initFlownsAdminStorage')

		expect(res).toBeNull()

	})

	test('init admin cap with root domain collection', async () => {

		const res = await buildSetupTrx('setupAdminServer', [])

		expect(res).not.toBeNull()

		const { status } = res

		// check

		expect(status).toBe(4)
	})

	// ...

})

import t from '@onflow/types'
import { fclInit, buildSetupTrx, buildAndExecScript, buildAndSendTrx } from '../utils/index.js'
import fcl from '@onflow/fcl'
import { accountAddr, flowTokenAddr } from '../config/constants.js'
import { test1Addr, test2Addr, test1Authz, test2Authz } from '../utils/authz.js'

// use admin to mint flow token
export const mintFlowToken = async (address, amount) => {

	await buildSetupTrx('mintFlowToken', [fcl.arg(address, t.Address), fcl.arg(amount, t.UFix64)])

}


// set test env
const main = async () => {

	// fcl init and load config

	fclInit()

	// mint token

	await mintFlowToken(test1Addr, '1000.00000000')

	await mintFlowToken(test2Addr, '1000.00000000')

	const balance = await buildAndExecScript('queryFlowTokenBalance', [fcl.arg(test2Addr, t.Address)])

	console.log(balance)

	// 通过测试账户初始化 Vault 资源
	await buildSetupTrx('initTokens', [], test1Authz())

	await buildSetupTrx('initTokens', [], test2Authz())

	// ....
	}



	main().then(() => process.exit(0))
	.catch((error) => {
	console.error(error)
	process.exit(1)

})

总结