Add comments to network client test functions (#1310)

JSDoc comments have been added to functions used for the network client
tests. These were copied from the extension.

This reduces the scope of #1116

packages/network-controller/tests/provider-api-tests/block-hash-in-response.ts

@@ -10,13 +10,25 @@ type TestsForRpcMethodThatCheckForBlockHashInResponseOptions = {
   numberOfParameters: number;
 };
 
-export const testsForRpcMethodsThatCheckForBlockHashInResponse = (
+/**
+ * Defines tests which exercise the behavior exhibited by an RPC method that
+ * use `blockHash` in the response data to determine whether the response is
+ * cacheable.
+ *
+ * @param method - The name of the RPC method under test.
+ * @param additionalArgs - Additional arguments.
+ * @param additionalArgs.numberOfParameters - The number of parameters supported
+ * by the method under test.
+ * @param additionalArgs.providerType - The type of provider being tested;
+ * either `infura` or `custom`.
+ */
+export function testsForRpcMethodsThatCheckForBlockHashInResponse(
   method: string,
   {
     providerType,
     numberOfParameters,
   }: TestsForRpcMethodThatCheckForBlockHashInResponseOptions,
-) => {
+) {
   it('does not hit the RPC endpoint more than once for identical requests and it has a valid blockHash', async () => {
     const requests = [{ method }, { method }];
     const mockResult = { blockHash: '0x1' };
@@ -227,4 +239,4 @@ export const testsForRpcMethodsThatCheckForBlockHashInResponse = (
       });
     });
   }
-};
+}

packages/network-controller/tests/provider-api-tests/block-param.ts

@@ -18,14 +18,28 @@ type TestsForRpcMethodSupportingBlockParam = {
   numberOfParameters: number;
 };
 
-export const testsForRpcMethodSupportingBlockParam = (
+/**
+ * Defines tests which exercise the behavior exhibited by an RPC method that
+ * takes a block parameter. The value of this parameter can be either a block
+ * number or a block tag ("latest", "earliest", or "pending") and affects how
+ * the method is cached.
+ *
+ * @param method - The name of the RPC method under test.
+ * @param additionalArgs - Additional arguments.
+ * @param additionalArgs.blockParamIndex - The index of the block parameter.
+ * @param additionalArgs.numberOfParameters - The number of parameters
+ * supported by the method under test.
+ * @param additionalArgs.providerType - The type of provider being tested.
+ * either `infura` or `custom`.
+ */
+export function testsForRpcMethodSupportingBlockParam(
   method: string,
   {
     blockParamIndex,
     numberOfParameters,
     providerType,
   }: TestsForRpcMethodSupportingBlockParam,
-) => {
+) {
   describe.each([
     ['given no block tag', undefined],
     ['given a block tag of "latest"', 'latest'],
@@ -1796,4 +1810,4 @@ export const testsForRpcMethodSupportingBlockParam = (
       });
     });
   }
-};
+}

packages/network-controller/tests/provider-api-tests/no-block-param.ts

@@ -44,13 +44,25 @@ type TestsForRpcMethodAssumingNoBlockParamOptions = {
   numberOfParameters: number;
 };
 
-export const testsForRpcMethodAssumingNoBlockParam = (
+/**
+ * Defines tests which exercise the behavior exhibited by an RPC method which is
+ * assumed to not take a block parameter. Even if it does, the value of this
+ * parameter will not be used in determining how to cache the method.
+ *
+ * @param method - The name of the RPC method under test.
+ * @param additionalArgs - Additional arguments.
+ * @param additionalArgs.numberOfParameters - The number of parameters
+ * supported by the method under test.
+ * @param additionalArgs.providerType - The type of provider being tested;
+ * either `infura` or `custom`.
+ */
+export function testsForRpcMethodAssumingNoBlockParam(
   method: string,
   {
     numberOfParameters,
     providerType,
   }: TestsForRpcMethodAssumingNoBlockParamOptions,
-) => {
+) {
   it('does not hit the RPC endpoint more than once for identical requests', async () => {
     const requests = [{ method }, { method }];
     const mockResults = ['first result', 'second result'];
@@ -913,4 +925,4 @@ export const testsForRpcMethodAssumingNoBlockParam = (
       });
     });
   }
-};
+}

packages/network-controller/tests/provider-api-tests/not-handled-by-middleware.ts

@@ -10,13 +10,24 @@ type TestsForRpcMethodNotHandledByMiddlewareOptions = {
   numberOfParameters: number;
 };
 
-export const testsForRpcMethodNotHandledByMiddleware = (
+/**
+ * Defines tests which exercise the behavior exhibited by an RPC method that
+ * is not handled specially by the network client middleware.
+ *
+ * @param method - The name of the RPC method under test.
+ * @param additionalArgs - Additional arguments.
+ * @param additionalArgs.providerType - The type of provider being tested;
+ * either `infura` or `custom`.
+ * @param additionalArgs.numberOfParameters - The number of parameters that this
+ * RPC method takes.
+ */
+export function testsForRpcMethodNotHandledByMiddleware(
   method: string,
   {
     providerType,
     numberOfParameters,
   }: TestsForRpcMethodNotHandledByMiddlewareOptions,
-) => {
+) {
   it('attempts to pass the request off to the RPC endpoint', async () => {
     const request = {
       method,
@@ -38,4 +49,4 @@ export const testsForRpcMethodNotHandledByMiddleware = (
       expect(actualResult).toStrictEqual(expectedResult);
     });
   });
-};
+}

packages/network-controller/tests/provider-api-tests/shared-tests.ts

@@ -11,23 +11,46 @@ import { testsForRpcMethodAssumingNoBlockParam } from './no-block-param';
 import { testsForRpcMethodNotHandledByMiddleware } from './not-handled-by-middleware';
 import { testsForRpcMethodWithStaticResult } from './static-results';
 
-export const buildInfuraClientRetriesExhaustedErrorMessage = (
-  reason: string,
-) => {
+/**
+ * Constructs an error message that the Infura client would produce in the event
+ * that it has attempted to retry the request to Infura and has failed.
+ *
+ * @param reason - The exact reason for failure.
+ * @returns The error message.
+ */
+export function buildInfuraClientRetriesExhaustedErrorMessage(reason: string) {
   return new RegExp(
     `^InfuraProvider - cannot complete request. All retries exhausted\\..+${reason}`,
     'us',
   );
-};
+}
 
-export const buildFetchFailedErrorMessage = (url: string, reason: string) => {
+/**
+ * Constructs an error message that `fetch` with throw if it cannot make a
+ * request.
+ *
+ * @param url - The URL being fetched
+ * @param reason - The reason.
+ * @returns The error message.
+ */
+export function buildFetchFailedErrorMessage(url: string, reason: string) {
   return new RegExp(
     `^request to ${url}(/[^/ ]*)+ failed, reason: ${reason}`,
     'us',
   );
-};
+}
 
-export const testsForProviderType = (providerType: ProviderType) => {
+/**
+ * Defines tests that are common to both the Infura and JSON-RPC network client.
+ *
+ * @param providerType - The type of provider being tested, which determines
+ * which suite of middleware is being tested. If `infura`, then the middleware
+ * exposed by `createInfuraClient` is tested; if `custom`, then the middleware
+ * exposed by `createJsonRpcClient` will be tested.
+ */
+export function testsForProviderType(providerType: ProviderType) {
+  // Ethereum JSON-RPC spec: <https://ethereum.github.io/execution-apis/api-documentation/>
+  // Infura documentation: <https://docs.infura.io/infura/networks/ethereum/json-rpc-methods>
   describe('methods included in the Ethereum JSON-RPC spec', () => {
     describe('methods not handled by middleware', () => {
       const notHandledByMiddleware = [
@@ -387,4 +410,4 @@ export const testsForProviderType = (providerType: ProviderType) => {
       });
     });
   });
-};
+}