From a419106c58b53c622e84e4788c2968667c899a99 Mon Sep 17 00:00:00 2001 From: Otto Allmendinger Date: Fri, 12 Apr 2024 09:57:33 +0200 Subject: [PATCH] docs(blockapis): improve documentation for UtxoApi test suite Issue: BTC-1084 --- modules/blockapis/test/UtxoApi.ts | 56 +++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/modules/blockapis/test/UtxoApi.ts b/modules/blockapis/test/UtxoApi.ts index a3e93cc5a2..e0dfc461d2 100644 --- a/modules/blockapis/test/UtxoApi.ts +++ b/modules/blockapis/test/UtxoApi.ts @@ -1,3 +1,11 @@ +/** + * This test suite iterates over a set of backends and test methods. + * + * For each backend and method, we test that the backend can fetch the resource. + * + * We then compare the normalized results from all backends to make sure they are the same. + */ + import 'mocha'; import * as assert from 'assert'; import { BlockchairApi, BlockstreamApi, UtxoApi, CachingHttpClient } from '../src'; @@ -34,13 +42,30 @@ function getTestTransactionIds(coinName: string): string[] { type MethodArguments = unknown[]; +/** + * A test case for a UtxoApi method. + */ class TestCase { + /** + * @param coinName - coin to test + * @param methodName - method to test + * @param args - method arguments + */ constructor(public coinName: string, public methodName: keyof UtxoApi, public args: unknown[]) {} + /** + * Call the method on the given API. + * @param api + */ func(api: UtxoApi) { return (api[this.methodName] as any)(...this.args); } + /** + * Get the fixture for this test case. + * @param api + * @param defaultValue + */ async getFixture(api: UtxoApi, defaultValue?: T): Promise { const filename = [ 'UtxoApi', @@ -53,6 +78,10 @@ class TestCase { return await getFixture(`${__dirname}/fixtures/${filename}`, defaultValue); } + /** + * Get the fixture, but with the API-specific fields removed. + * @param api + */ async getFixtureNormal(api: UtxoApi): Promise { if (this.methodName === 'getTransactionStatus') { // remove api-specific fields @@ -78,6 +107,9 @@ class TestCase { return false; } + /** + * @return a human-readable title for this test case. + */ title(): string { function elide(s: string, len: number) { return s.length > len ? `${s.slice(0, len)}...` : s; @@ -86,10 +118,18 @@ class TestCase { } } +/** + * @param name + * @return a new CachingHttpClient that reads from the given fixture directory. + */ function getHttpClient(name: string): CachingHttpClient { return new CachingHttpClient(`${__dirname}/fixtures/responses/` + name, { isHttpEnabled: isHttpEnabled() }); } +/** + * @param coinName + * @return a list of APIs to test. + */ function getApis(coinName: string): UtxoApi[] { if (coinName === 'tbtc') { return [ @@ -101,6 +141,10 @@ function getApis(coinName: string): UtxoApi[] { return []; } +/** + * @param coinName + * @return a list of test cases for the given coin. + */ function getTestCases(coinName: string): TestCase[] { function getArguments(coinName: string, methodName: keyof UtxoApi): MethodArguments[] { switch (methodName) { @@ -130,6 +174,12 @@ function getTestCases(coinName: string): TestCase[] { ); } +/** + * Set up fetch tests for the given API. + * + * @param api + * @param coinName + */ function runTestFetch(api: UtxoApi, coinName: string) { getTestCases(coinName).forEach((testCase) => { describe(`${api.constructor.name} ${testCase.title()}`, function () { @@ -146,6 +196,12 @@ function runTestFetch(api: UtxoApi, coinName: string) { }); } +/** + * Set up comparison tests for the given API. + * + * @param api + * @param coinName + */ function runTestCompare(api: UtxoApi, coinName: string) { getTestCases(coinName).forEach((testCase) => { describe(`method ${testCase.title()}`, function () {