docs: add test report

README.md

@@ -95,6 +95,15 @@ cabal build all
 
 ![plutarch-design-patterns.gif](/assets/images/plutarch-design-patterns.gif)
 
+Test:
+
+```sh
+cabal test --test-show-details=direct
+```
+
+![test_report.png](/assets/images/test_report.png)
+
+
 ## Provided Patterns
 
 ### Stake Validator

test/Spec/MerkelizedValidatorSpec.hs

@@ -1,3 +1,7 @@
+{- |
+Module      : Spec.MerkelizedValidatorSpec
+Description : Test suite for the Merkelized Validator functions in a Plutarch smart contract environment.
+-}
 module Spec.MerkelizedValidatorSpec (
   psumOfSquares,
   spendUnitTest,
@@ -35,12 +39,14 @@ import "liqwid-plutarch-extra" Plutarch.Extra.TermCont (
   pletFieldsC,
  )
 
+-- | Calculates the sum of squares of integers provided as a list of 'PData'.
 psumOfSquares :: (PIsListLike list PData, PIsListLike list PInteger) => Term s (PBuiltinList PData :--> list PData)
 psumOfSquares =
   plam $ \xs ->
     let result = pfoldl # plam (\y x -> (x #* x) #+ y) # 0 # (pmap # pasInt # xs)
      in psingleton # pdataImpl result
 
+-- | Validates a transaction based on a predefined logic involving a sum less than a threshold value.
 spend :: Term s PStakingCredential -> Term s PValidator
 spend stakeCred =
   plam $ \x y ctx -> unTermCont $ do
@@ -54,6 +60,7 @@ spend stakeCred =
         (popaque $ pconstant ())
         perror
 
+-- | Merkelized withdrawal function that validates state transitions based on sum of squares calculation.
 withdraw :: Term s PStakeValidator
 withdraw = MerkelizedValidator.withdraw psumOfSquares
 
@@ -93,6 +100,7 @@ withdrawCtx =
       [ withdrawal rewardingCred 1
       ]
 
+-- | Tests the 'spend' function for both successful and failed validation scenarios.
 spendUnitTest :: TestTree
 spendUnitTest = tryFromPTerm "Merkelized Validator Spend Unit Test" (spend stakeCred) $ do
   testEvalCase
@@ -103,13 +111,14 @@ spendUnitTest = tryFromPTerm "Merkelized Validator Spend Unit Test" (spend stake
     , PlutusTx.toData spendCtx
     ]
   testEvalCase
-    "Fail - Spend"
+    "Fail - Spend incorrect datum and redeemer"
     Failure
     [ PlutusTx.toData (3 :: Integer)
     , PlutusTx.toData (4 :: Integer)
     , PlutusTx.toData spendCtx
     ]
 
+-- | Tests the 'withdraw' function to ensure correct state transition validations.
 withdrawUnitTest :: TestTree
 withdrawUnitTest = tryFromPTerm "Merkelized Validator Withdraw Unit Test" withdraw $ do
   testEvalCase

test/Spec/MultiUTxOIndexerOneToManySpec.hs

@@ -1,3 +1,7 @@
+{- |
+Module      : Spec.MultiUTxOIndexerOneToManySpec
+Description : Test suite for validating UTxO indexation in a multi-validator setup using the Plutarch environment.
+-}
 module Spec.MultiUTxOIndexerOneToManySpec (
   validator,
   unitTest,
@@ -36,12 +40,15 @@ import PlutusTx.Builtins (mkI)
 import Spec.Utils qualified as Utils
 import Test.Tasty (TestTree)
 
+-- | Handles the spend logic using the basic Stake Validator.
 spend :: Term s PValidator
 spend = StakeValidator.spend
 
+-- | Handles withdrawal logic with additional indexing validations for multi-UTxO scenarios.
 withdraw :: Term s PStakeValidator
 withdraw = MultiUTxOIndexerOneToMany.withdraw Utils.inputValidator Utils.inputOutputValidator Utils.collectiveOutputValidator
 
+-- | Combines staking and spending validation into a single composite validator.
 validator :: Term s PValidator
 validator = Multivalidator.multivalidator withdraw spend
 
@@ -72,6 +79,7 @@ outputUTXO =
     , withValue (singleton "" "" 4_000_000)
     ]
 
+-- | Context setup for spend transactions including mock UTxOs and withdrawal.
 spendCtx :: ScriptContext
 spendCtx =
   buildSpending' $
@@ -99,6 +107,7 @@ badRedeemer =
         }
     ]
 
+-- | Context setup for withdrawal transactions, integrating input and output UTxOs.
 withdrawCtx :: ScriptContext
 withdrawCtx =
   buildRewarding' $
@@ -108,6 +117,7 @@ withdrawCtx =
       , withRewarding rewardingCred
       ]
 
+-- | Primary unit tests for validating the correct and incorrect behaviors of spend and withdraw functions.
 unitTest :: TestTree
 unitTest = tryFromPTerm "Multi UTxO Indexer One To Many Unit Test" validator $ do
   testEvalCase

test/Spec/MultiUTxOIndexerSpec.hs

@@ -1,3 +1,7 @@
+{- |
+Module      : Spec.MultiUTxOIndexerSpec
+Description : Test suite for MultiUTxO Indexer validation in a Plutarch-based smart contract setting.
+-}
 module Spec.MultiUTxOIndexerSpec (
   validator,
   unitTest,
@@ -42,6 +46,7 @@ spend = StakeValidator.spend
 withdraw :: Term s PStakeValidator
 withdraw = MultiUTxOIndexer.withdraw Utils.inputOutputValidator
 
+-- | A combined validator that integrates both staking and spending validation logic.
 validator :: Term s PValidator
 validator = Multivalidator.multivalidator withdraw spend
 
@@ -72,6 +77,7 @@ outputUTXO =
     , withValue (singleton "" "" 4_000_000)
     ]
 
+-- | A script context for spend transactions, incorporating UTxO details and withdrawal credentials.
 spendCtx :: ScriptContext
 spendCtx =
   buildSpending' $
@@ -99,6 +105,7 @@ badRedeemer =
         }
     ]
 
+-- | A script context for withdraw transactions, using input and output UTxOs.
 withdrawCtx :: ScriptContext
 withdrawCtx =
   buildRewarding' $
@@ -108,6 +115,7 @@ withdrawCtx =
       , withRewarding rewardingCred
       ]
 
+-- | Unit tests evaluating the correct operation of the validator under various scenarios.
 unitTest :: TestTree
 unitTest = tryFromPTerm "Multi UTxI Indexer Unit Test" validator $ do
   testEvalCase

test/Spec/SingularUTxOIndexerOneToManySpec.hs

@@ -1,3 +1,7 @@
+{- |
+Module      : Spec.SingularUTxOIndexerOneToManySpec
+Description : Test suite for Singular UTxO Indexer in a one-to-many configuration using Plutarch.
+-}
 module Spec.SingularUTxOIndexerOneToManySpec (
   spend,
   unitTest,
@@ -32,6 +36,7 @@ import PlutusTx.Builtins (mkI)
 import Spec.Utils qualified as Utils
 import Test.Tasty (TestTree)
 
+-- | A validator that enforces one-to-many UTxO indexing rules for spend transactions.
 spend :: Term s PValidator
 spend = SingularUTxOIndexerOneToMany.spend Utils.inputValidator Utils.inputOutputValidator Utils.collectiveOutputValidator
 
@@ -76,6 +81,7 @@ badRedeemer =
     , outIxs = [mkI 1]
     }
 
+-- | Script context for spending tests, incorporating input and output UTxOs, and other contextual information.
 spendCtx :: ScriptContext
 spendCtx =
   buildSpending' $
@@ -86,6 +92,7 @@ spendCtx =
       , withdrawal rewardingCred 1
       ]
 
+-- | Unit tests that validate the correct operation and rejection scenarios of the spend validator.
 unitTest :: TestTree
 unitTest = tryFromPTerm "Singular UTxO Indexer One To Many Unit Test" spend $ do
   testEvalCase

test/Spec/SingularUTxOIndexerSpec.hs

@@ -1,3 +1,7 @@
+{- |
+Module      : Spec.SingularUTxOIndexerSpec
+Description : Test suite for Singular UTxO Indexer validation in Plutarch, focusing on single input-output pair indexing.
+-}
 module Spec.SingularUTxOIndexerSpec (
   spend,
   unitTest,
@@ -32,6 +36,7 @@ import PlutusTx.Builtins (mkI)
 import Spec.Utils qualified as Utils
 import Test.Tasty (TestTree)
 
+-- | Implements a validator that enforces specific UTxO spending rules using input-output pair indexing.
 spend :: Term s PValidator
 spend = SingularUTxOIndexer.spend Utils.inputOutputValidator
 
@@ -62,20 +67,23 @@ outputUTXO =
     , withValue (singleton "" "" 4_000_000)
     ]
 
+-- | Redeemer configuration for the validator, specifying the correct indexing of input and output UTxOs.
 redeemer :: SingularUTxOIndexer.SpendRedeemer
 redeemer =
   SingularUTxOIndexer.SpendRedeemer
     { inIdx = mkI 0
     , outIdx = mkI 0
     }
 
+-- | A misconfigured redeemer that is expected to cause the validator to fail, demonstrating error handling.
 badRedeemer :: SingularUTxOIndexer.SpendRedeemer
 badRedeemer =
   SingularUTxOIndexer.SpendRedeemer
     { inIdx = mkI 0
     , outIdx = mkI 1
     }
 
+-- | Context setup for spending tests, incorporating input and output UTxOs, withdrawal credentials.
 spendCtx :: ScriptContext
 spendCtx =
   buildSpending' $
@@ -86,6 +94,7 @@ spendCtx =
       , withdrawal rewardingCred 1
       ]
 
+-- | Unit tests to verify the validator's functionality under both correct and incorrect scenarios.
 unitTest :: TestTree
 unitTest = tryFromPTerm "Singular UTxO Indexer Unit Test" spend $ do
   testEvalCase

test/Spec/StakeValidatorSpec.hs

@@ -1,3 +1,7 @@
+{- |
+Module      : Spec.StakeValidatorSpec
+Description : Test suite for the Stake Validator in a Plutarch smart contract environment.
+-}
 module Spec.StakeValidatorSpec (
   validator,
   unitTest,
@@ -34,9 +38,11 @@ import PlutusLedgerApi.V2 (
 import PlutusTx qualified
 import Test.Tasty (TestTree)
 
+-- | Implements the spending logic.
 spend :: Term s PValidator
 spend = StakeValidator.spend
 
+-- | Implements the withdrawal logic.
 withdrawLogic :: Term s (PData :--> PStakingCredential :--> PTxInfo :--> PUnit)
 withdrawLogic =
   plam $ \_ _ _ -> unTermCont $ do
@@ -45,6 +51,7 @@ withdrawLogic =
 withdraw :: Term s PStakeValidator
 withdraw = StakeValidator.withdraw withdrawLogic
 
+-- | Core validator that combines spend and withdraw functionalities.
 validator :: Term s PValidator
 validator = Multivalidator.multivalidator withdraw spend
 
@@ -68,6 +75,7 @@ inputUTXO =
     , withRefIndex 1
     ]
 
+-- | Context setup for standard spend tests including necessary UTxO and withdrawal credentials.
 spendCtx :: ScriptContext
 spendCtx =
   buildSpending' $
@@ -86,17 +94,20 @@ spendIncorrectOutRefCtx =
       , withdrawal rewardingCred 1
       ]
 
+-- | Context setup for successful withdrawal tests.
 withdrawCtx :: ScriptContext
 withdrawCtx =
   buildRewarding' $
     mconcat
       [ withRewarding rewardingCred
       ]
 
+-- | Context setup for withdrawal tests expected to fail.
 badWithdrawCtx :: ScriptContext
 badWithdrawCtx =
   buildSpending' $ mconcat []
 
+-- | Unit tests to verify the correct behavior and error handling of the validator under various scenarios.
 unitTest :: TestTree
 unitTest = tryFromPTerm "Stake Validator Unit Test" validator $ do
   testEvalCase

test/Spec/TxLevelMinterSpec.hs

@@ -1,3 +1,7 @@
+{- |
+Module      : Spec.TxLevelMinterSpec
+Description : Test suite for a transaction-level minter validator in a Plutarch smart contract environment.
+-}
 module Spec.TxLevelMinterSpec (
   validator,
   unitTest,
@@ -35,19 +39,23 @@ import PlutusLedgerApi.V2 (
 import PlutusTx qualified
 import Test.Tasty (TestTree)
 
+-- | Implements the spending logic, including validation of the custom token 'BEACON'.
 spend :: Term s PValidator
 spend = phoistAcyclic $
   plam $ \_ redeemer ctx -> unTermCont $ do
     return (popaque $ TxLevelMinter.spend # pconstant "BEACON" # redeemer # ctx)
 
+-- | Simple minting logic that just returns unit (no actual validation logic included for simplicity).
 mintLogic :: Term s (PData :--> PCurrencySymbol :--> PTxInfo :--> PUnit)
 mintLogic =
   plam $ \_ _ _ -> unTermCont $ do
     pure $ pconstant ()
 
+-- | Minting policy that encapsulates the minting behavior.
 mintingPolicy :: Term s PMintingPolicy
 mintingPolicy = TxLevelMinter.mint mintLogic
 
+-- | Core validator that combines spending and minting functionalities into a single validator logic.
 validator :: Term s PValidator
 validator = Multivalidator.multivalidator mintingPolicy spend
 
@@ -74,6 +82,7 @@ inputUTXO =
 mintedValue :: Value
 mintedValue = singleton "65c4b5e51c3c58c15af080106e8ce05b6efbb475aa5e5c5ca9372a45" "BEACON" 1
 
+-- | Context for spend validation, including input, output, withdrawal of staking credentials, and minting of a token.
 spendCtx :: ScriptContext
 spendCtx =
   buildSpending' $
@@ -84,13 +93,15 @@ spendCtx =
       , mint mintedValue
       ]
 
+-- | Context for validating minting actions, configured to handle the minting of the custom token.
 mintCtx :: ScriptContext
 mintCtx =
   buildMinting' $
     mconcat
       [ mint mintedValue
       ]
 
+-- | Unit tests to ensure the validator behaves as expected under various scenarios including correct and incorrect token minting.
 unitTest :: TestTree
 unitTest = tryFromPTerm "Tx Level Minter Unit Test" validator $ do
   testEvalCase