refactor: update documentation to match the newly refactored application spy

Author: boblat

docs/code/index/classes/ApplicationSpy.md

@@ -6,25 +6,25 @@
 
 # Class: ApplicationSpy\<TContract\>
 
-Defined in: [src/application-spy.ts:33](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L33)
+Defined in: [src/application-spy.ts:32](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L32)
 
 ## Type Parameters
 
 ### TContract
 
-`TContract` *extends* `Contract`
+`TContract` *extends* `Contract` = `Contract`
 
 ## Constructors
 
 ### Constructor
 
-> **new ApplicationSpy**\<`TContract`\>(`contract`): `ApplicationSpy`\<`TContract`\>
+> **new ApplicationSpy**\<`TContract`\>(`contract`?): `ApplicationSpy`\<`TContract`\>
 
-Defined in: [src/application-spy.ts:45](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L45)
+Defined in: [src/application-spy.ts:44](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L44)
 
 #### Parameters
 
-##### contract
+##### contract?
 
 `TContract` | `ConstructorFor`\<`TContract`\>
 
@@ -34,19 +34,19 @@ Defined in: [src/application-spy.ts:45](https://github.com/algorandfoundation/al
 
 ## Properties
 
-### contract
+### contract?
 
-> **contract**: `TContract` \| `ConstructorFor`\<`TContract`\>
+> `optional` **contract**: `TContract` \| `ConstructorFor`\<`TContract`\>
 
-Defined in: [src/application-spy.ts:43](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L43)
+Defined in: [src/application-spy.ts:42](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L42)
 
 ***
 
 ### on
 
 > `readonly` **on**: `_TypedApplicationSpyCallBacks`\<`TContract`\>
 
-Defined in: [src/application-spy.ts:40](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L40)
+Defined in: [src/application-spy.ts:39](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L39)
 
 The `on` property is a proxy that allows you to register callbacks for specific method signatures.
 It dynamically creates methods based on the contract's methods.
@@ -57,7 +57,7 @@ It dynamically creates methods based on the contract's methods.
 
 > **notify**(`itxn`): `void`
 
-Defined in: [src/application-spy.ts:51](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L51)
+Defined in: [src/application-spy.ts:50](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L50)
 
 #### Parameters
 
@@ -71,19 +71,43 @@ Defined in: [src/application-spy.ts:51](https://github.com/algorandfoundation/al
 
 ***
 
+### onAbiCall()
+
+> **onAbiCall**(`methodSignature`, `callback`): `void`
+
+Defined in: [src/application-spy.ts:69](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L69)
+
+Registers a callback for a specific method signature.
+
+#### Parameters
+
+##### methodSignature
+
+`bytes`
+
+##### callback
+
+`AppSpyCb`
+
+#### Returns
+
+`void`
+
+***
+
 ### onBareCall()
 
 > **onBareCall**(`callback`): `void`
 
-Defined in: [src/application-spy.ts:61](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L61)
+Defined in: [src/application-spy.ts:60](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L60)
 
 Registers a callback for a bare call (no arguments).
 
 #### Parameters
 
 ##### callback
 
-`AppSpyCb`\<\[\], `unknown`\>
+`AppSpyCb`
 
 The callback to be executed when a bare call is detected.
 

docs/code/subcontexts/contract-context/classes/ContractContext.md

@@ -6,7 +6,7 @@
 
 # Class: ContractContext
 
-Defined in: [src/subcontexts/contract-context.ts:145](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/contract-context.ts#L145)
+Defined in: [src/subcontexts/contract-context.ts:146](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/contract-context.ts#L146)
 
 Provides a context for creating contracts and registering created contract instances
 with test execution context.
@@ -27,7 +27,7 @@ with test execution context.
 
 > **create**\<`T`\>(`type`, ...`args`): `T`
 
-Defined in: [src/subcontexts/contract-context.ts:157](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/contract-context.ts#L157)
+Defined in: [src/subcontexts/contract-context.ts:158](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/contract-context.ts#L158)
 
 Creates a new contract instance and register the created instance with test execution context.
 
@@ -72,7 +72,7 @@ const contract = ctx.contract.create(MyContract);
 
 > `static` **createMethodCallTxns**\<`TParams`\>(`contract`, `abiMetadata`, ...`args`): `Transaction`[]
 
-Defined in: [src/subcontexts/contract-context.ts:179](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/contract-context.ts#L179)
+Defined in: [src/subcontexts/contract-context.ts:180](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/contract-context.ts#L180)
 
 **`Internal`**
 

docs/testing-guide/application-spy.md

@@ -46,8 +46,8 @@ const spy = new ApplicationSpy(Hello)
 
 // register a callback for the method of the contract.
 // the callback is registered against the method selector.
-// callbacks for multiple methods with same method selector are kept in an array
-// and all callbacks are invoked when any one of those methods is called.
+// all callbacks for multiple methods with same method selector are invoked
+// when any one of those methods is called.
 // in those cases, you can check for `itxnContext.approvalProgram` or `itxnContext.appId`
 // to see if the callback needs to handle a particular method call.
 // e.g.
@@ -57,10 +57,9 @@ const spy = new ApplicationSpy(Hello)
 // }
 // ```
 // `itxnContext` is provided as a parameter to the callback method and
-// it allows reading and setting of all properties of `itxn.ApplicationCallFields` interface
-// which are used to construct `itxn.ApplicationCall` transaction when `.submit()` is called.
-// it also maps `appArgs` to `args` property and provides consistent access to parameters passed
-// to the contract method.
+// it allows reading and setting of the properties of `itxn.ApplicationCallInnerTxn` interface.
+// it also maps and encodes the arugments to `appArgs` collection as bytes values,
+// and provides consistent access those arguments.
 spy.on.create((itxnContext) => {
   itxnContext.createdApp = helloApp
 })
@@ -98,7 +97,7 @@ ctx.setCompiledApp(Hello, helloApp.id)
 const spy = new ApplicationSpy(Hello)
 
 // the mock setup is the same as using explicit create method except
-// the literal string keyword 'bareCreate' is used instead of a method signature
+// `onBareCall` method is used instead of `on.{methodName}` or `onAbiCall` methods
 // to register the callback
 spy.onBareCall((itxnContext) => {
   itxnContext.createdApp = helloApp
@@ -119,51 +118,54 @@ const txn = itxn
 const result = decodeArc4<string>(txn.lastLog, 'log')
 ```
 
-Mock result can be setup for the snippet above as
+**2. Strongly typed contract method call**
+
+```ts
+const result = compiled.call.greet({
+  args: ['world'],
+  appId: app,
+}).returnValue
+assert(result === 'hello world')
+```
+
+Mock result can be setup for both snippets above as
 
 ````ts
-// `itxnContext.returnValue` is added as the last entry to the logs of the constructed `itxn.ApplicationCall`
+// `itxnContext.setReturnValue` is added as the last entry to the logs of the constructed `itxn.ApplicationCall`
 // so that it can be access via `txn.lastLog` property.
-// it is available as `.retrunValue` when using strongly typed method call approach.
-// `returnValue` should only be set as the last statement of the callback and
+// `setReturnValue` should only be called as the last statement of the callback and
 // especially no further manipulations of logs should take place afterwards.
-// `appArgs` without the first value (which is the method selector) is available as `itxnContext.args`.
-// since it is encoded as `bytes`, it needs to be decoded to get back the string value.
+// `appArgs` collection holds method selector and method arguments encoded as `bytes` values.
+// They need to be decoded if the orginal argument values are needed.
 // you can check `itxnContext.appId` if there are multiple callback registered for the same method selector
 // e.g.
 // ```
 // if (itxnContext.appId === helloApp) {
-//   itxnContext.returnValue = `hello ${decodeArc4<Str>(itxnContext.args[0])}`
+//   itxnContext.returnValue = `hello ${decodeArc4<string>(itxnContext.appArgs(0))}`
 // }
 // ```
 spy.on.greet((itxnContext) => {
-  itxnContext.returnValue = `hello ${decodeArc4<Str>(itxnContext.args[0])}`
+  itxnContext.returnValue = `hello ${decodeArc4<string>(itxnContext.appArgs(0))}`
 })
 ````
 
-**2. Strongly typed contract method call**
-
-```ts
-const result = compiled.call.greet({
-  args: ['world'],
-  appId: app,
-}).returnValue
-assert(result === 'hello world')
-```
-
-Mock result can be setup for the snippet above as
+You can also use the alternative approach below to setup the mock result. It is especially useful if you do not have `Contract` subclass available and only method signature and application id are availbe to make the method call.
 
 ```ts
-// the setup is the same as in `itxn.applicationCall`, except the `itxnContext.args` contains
-// the values passed in `args` array in their original format with being encoded into bytes.
-spy.on.greet((itxnContext) => {
-  itxnContext.returnValue = `hello ${itxnContext.args[0]}`
+// create a spy without the contract type provided
+const spy = new ApplicationSpy()
+
+spy.onAbiCall(methodSelector('greet(string)string'), (itxnContext) => {
+  // check for a well-known appId or the appId provided to the contract under test in some other manner
+  if (itxnContext.appId === appId) {
+    itxnContext.setReturnValue(`hey ${decodeArc4<string>(itxnContext.appArgs(1))}`)
+  }
 })
 ```
 
 **3. Strongly typed ABI calls**
 
-```
+```ts
 const result = abiCall(Hello.prototype.greet, {
   appId: app,
   args: ['abi'],
@@ -175,41 +177,10 @@ Mock result can be setup for the snippet above as
 ```ts
 // the setup is the same as the previous case
 spy.on.greet((itxnContext) => {
-  itxnContext.returnValue = `hello ${itxnContext.args[0]}`
+  itxnContext.setReturnValue(`hello ${decodeArc4<string>(itxnContext.appArgs(0))}`)
 })
 ```
 
-### Key Features
-
-1. **Type-safe Method Mocking**
-
-   ```ts
-   spy.on.increment((itxnContext) => {
-     // itxnContext.args is properly typed based on method signature
-     itxnContext.returnValue = 1n // Type checked against method return type
-   })
-   ```
-
-2. **Creation Handling**
-
-   ```ts
-   spy.on.create((itxnContext) => {
-     // Handle contract creation
-     itxnContext.createdApp = counterApp
-   })
-   ```
-
-3. **Multiple Contract Support**
-
-   ```ts
-   // Create spies for different contracts
-   const counterSpy = new ApplicationSpy(Counter)
-   const vaultSpy = new ApplicationSpy(Vault)
-
-   ctx.addApplicationSpy(counterSpy)
-   ctx.addApplicationSpy(vaultSpy)
-   ```
-
 ### Best Practices
 
 1. **Reset Between Tests**
@@ -226,15 +197,16 @@ spy.on.greet((itxnContext) => {
    spy.on.increment((itxnContext) => {
      // Only handle calls to specific app instance
      if (itxnContext.appId === counterApp) {
-       itxnContext.returnValue = 1n
+       itxnContext.setReturnValue(1n)
      }
    })
    ```
 
 3. **Handle Method Arguments**
    ```ts
    spy.on.setValue((itxnContext) => {
-     //`itxnContext.args` could be encoded as bytes if `itxn.applicationCall` is used to make the call
-     itxnContext.returnValue = `hello ${decodeArc4<Str>(itxnContext.args[0])}`
+     // arguments provided to the method are encoded as bytes values
+     // and available via `itxnContext.appArgs` method
+     itxnContext.setReturnValue(`hello ${decodeArc4<string>(itxnContext.appArgs(0))}`)
    })
    ```

docs/testing-guide/transactions.md

@@ -189,7 +189,6 @@ If your contract needs to deploy other contracts then it's likely you will need
 ```ts
 import { assert, compile, Contract, GlobalState, itxn, OnCompleteAction } from '@algorandfoundation/algorand-typescript'
 import { ApplicationSpy, TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
-import type { Str } from '@algorandfoundation/algorand-typescript/arc4'
 import { abimethod, decodeArc4, encodeArc4, methodSelector } from '@algorandfoundation/algorand-typescript/arc4'
 import { afterEach, describe, it } from 'vitest'
 
@@ -257,7 +256,7 @@ describe('pre compiled app calls', () => {
       itxnContext.createdApp = helloApp
     })
     spy.on.greet((itxnContext) => {
-      itxnContext.returnValue = `hello ${decodeArc4<Str>(itxnContext.args[0])}`
+      itxnContext.setReturnValue(`hello ${decodeArc4<string>(itxnContext.appArgs(1))}`)
     })
     ctx.addApplicationSpy(spy)
 
@@ -274,9 +273,9 @@ describe('pre compiled app calls', () => {
 Assuming the contract you wish to compile extends the ARC4 `Contract` type, you can make use of `compileArc4` to produce a contract proxy object that makes it easy to invoke application methods with compile time type safety. You can use the same `ctx.setCompiledApp` method set up the mock result for `compile` call and `ApplicationSpy` for mocking subsequent calls to the compiled contract.
 
 ```ts
-import { assert, Contract, GlobalState, OnCompleteAction } from '@algorandfoundation/algorand-typescript'
+import { assert, Contract, GlobalState } from '@algorandfoundation/algorand-typescript'
 import { ApplicationSpy, TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
-import { abimethod, compileArc4 } from '@algorandfoundation/algorand-typescript/arc4'
+import { abimethod, compileArc4, decodeArc4 } from '@algorandfoundation/algorand-typescript/arc4'
 import { afterEach, describe, it } from 'vitest'
 
 export class Hello extends Contract {
@@ -332,10 +331,7 @@ describe('pre compiled typed app calls', () => {
       itxnContext.createdApp = helloApp
     })
     spy.on.greet((itxnContext) => {
-      itxnContext.returnValue = `hello ${itxnContext.args[0]}`
-    })
-    spy.on.delete((itxnContext) => {
-      itxnContext.onCompletion = OnCompleteAction.DeleteApplication
+      itxnContext.setReturnValue(`hello ${decodeArc4<string>(itxnContext.appArgs(1))}`)
     })
     ctx.addApplicationSpy(spy)
 
@@ -355,7 +351,7 @@ If your use case does not require deploying another contract, and instead you ar
 import type { Application } from '@algorandfoundation/algorand-typescript'
 import { assert, Contract, GlobalState } from '@algorandfoundation/algorand-typescript'
 import { ApplicationSpy, TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
-import { abiCall, abimethod } from '@algorandfoundation/algorand-typescript/arc4'
+import { abiCall, abimethod, decodeArc4 } from '@algorandfoundation/algorand-typescript/arc4'
 import { afterEach, describe, it } from 'vitest'
 
 export class Hello extends Contract {
@@ -398,7 +394,7 @@ describe('pre compiled typed app calls', () => {
 
     const spy = new ApplicationSpy(Hello)
     spy.on.greet((itxnContext) => {
-      itxnContext.returnValue = `hello ${itxnContext.args[0]}`
+      itxnContext.setReturnValue(`hello ${decodeArc4<string>(itxnContext.appArgs(1))}`)
     })
     ctx.addApplicationSpy(spy)
 

src/application-spy.ts

@@ -61,6 +61,11 @@ export class ApplicationSpy<TContract extends Contract = Contract> {
     this.#spyFns.push(predicates.bareCall(callback))
   }
 
+  /**
+   * Registers a callback for a specific method signature.
+   * @param methodSignature
+   * @param callback
+   */
   onAbiCall(methodSignature: bytes, callback: AppSpyCb) {
     this.#spyFns.push(predicates.methodSelector(callback, methodSignature))
   }