From ccd7e851b5b1b1fd23555bfcebdc077786478225 Mon Sep 17 00:00:00 2001 From: sourabhxyz Date: Fri, 13 Dec 2024 18:01:15 +0530 Subject: [PATCH] docs(#98): update testing section, improve previous sections --- .../home/components/DescriptionSection.tsx | 2 +- src/pages/getting-started/operations.mdx | 20 +++++++++++++ src/pages/getting-started/testing.mdx | 28 +++++++------------ 3 files changed, 31 insertions(+), 19 deletions(-) diff --git a/src/module/home/components/DescriptionSection.tsx b/src/module/home/components/DescriptionSection.tsx index 6eb0c92..b77b02e 100644 --- a/src/module/home/components/DescriptionSection.tsx +++ b/src/module/home/components/DescriptionSection.tsx @@ -234,7 +234,7 @@ const RightRow = styled(Grid)(({ theme }) => ({ }, })); -const IllustrationWrapper = styled(Grid)(({ }) => ({ +const IllustrationWrapper = styled(Grid)(({}) => ({ margin: "0 auto", })); diff --git a/src/pages/getting-started/operations.mdx b/src/pages/getting-started/operations.mdx index 59a28fb..035ad67 100644 --- a/src/pages/getting-started/operations.mdx +++ b/src/pages/getting-started/operations.mdx @@ -331,4 +331,24 @@ We weren't minting any tokens in our example here and thus didn't make use of `m We haven't made use of withdrawals, stake certificates and stake validators in our example. A sample illustration is provided in [this](https://github.com/geniusyield/atlas/blob/main/tests-privnet/GeniusYield/Test/Privnet/Stake.hs) privnet test. +## Monad hierarchy + +In Atlas we have hierarchy of monads with increasing level of capabilities. We already introduced `GYTxQueryMonad`. Besides it, we also have following monads. Don't worry if it appears overwhelming, they are mainly there for advanced usage and you would very rarely need to bother about their internals. + +### [`GYTxUserQueryMonad`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#t:GYTxUserQueryMonad) + +`GYTxQueryMonad` is a super-class of [`GYTxUserQueryMonad`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#t:GYTxUserQueryMonad). It is to be used for queries which have access to user's wallet details, such as change address, used addresses and so on. Please have a look at it's haddock entry [here](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#t:GYTxUserQueryMonad) to see for available functions. + +### [`GYTxBuilderMonad`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#t:GYTxBuilderMonad) + +`GYTxUserQueryMonad` is a superclass of [`GYTxBuilderMonad`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#t:GYTxBuilderMonad). Purpose of `GYTxBuilderMonad` is to allow for functions related to transaction building. This however could have been part of `GYTxUserQueryMonad` but is separate only to allow for different custom transaction building strategy to be used as default. As we will soon see, in our code, we would use [`buildTxBody`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#v:buildTxBody) to build for transaction, and that would be possible only if we are working inside `GYTxBuilderMonad`. + +### [`GYTxMonad`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#t:GYTxMonad) + +`GYTxBuilderMonad` is a superclass of [`GYTxMonad`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#t:GYTxMonad). Different between `GYTxMonad` and `GYTxBuilderMonad` is that former allows for signing of transactions, thus it requires access to user's private key. The main function we would encounter from this class is [`signAndSubmitConfirmed`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#v:signAndSubmitConfirmed). + +### [`GYTxGameMonad`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#t:GYTxMonad) + +`GYTxMonad` is a superclass of [`GYTxGameMonad`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#t:GYTxMonad). This monad allows for simulating multiple users, and is mainly used for testing. We touch more on it in our [testing](./testing) section. + [^1]: This is making use of _"singletons"_ and one can read about it from the "Dependent Types" chapter (the last one) in [Thinking with Types](https://thinkingwithtypes.com/) book. diff --git a/src/pages/getting-started/testing.mdx b/src/pages/getting-started/testing.mdx index 4fd79bf..ec6c169 100644 --- a/src/pages/getting-started/testing.mdx +++ b/src/pages/getting-started/testing.mdx @@ -16,15 +16,14 @@ plenty of techniques and approaches. Let's focus on __levels__ at which we can perform testing: * **Testing of UPLC functions.** You may want to verify that individual functions - your validators or minting policies consist of, indeed hold some properties. This is + your validators consist of, indeed hold some properties. This is useful if your on-chain logic is convoluted and involves complex computations. This level is tightly coupled to the language you use to build your smart contracts - so you should consult the documentation. + so you should consult the respective documentation. * **Testing of individual contracts (script level).** You might want to verify that the on-chain contracts you developed behave as expected - in isolation just by calling them with hand-constructed arguments for datum, - redeemer, and script context (since they are just functions after all) + in isolation just by calling them with hand-constructed arguments (like script context) since they are just functions after all and checking the results. Here again, you can use language-specific tools. But in case your contracts are already compiled down to UPLC code, you will need a special testing framework to do that. @@ -32,16 +31,13 @@ perform testing: namely [liqwid-context-builder](https://github.com/Liqwid-Labs/liqwid-libs/tree/main/plutarch-context-builder) from Liqwid's Libs mono repo. It allows one to easily construct various transaction contexts and verify a result that a particular script evaluates. - Testing of individual contracts proved to be very fruitful for both simple - and complex applications since it discovers bugs at very early stages - even before operations are defined. * **Testing of operations (transactions).** At this level, one can execute whole operations (transactions) an application provides and verifies that they a) can run through and b) confirm that some conditions we are interested in are held. A nice thing to know about Atlas is that it allows you to reuse the code for operations - you created in the previous step [Operations over Contract](./operations.mdx). + you created in the previous step, "[Operations over Contract](./operations.mdx)". This is the level of testing we discuss in this section. You can also make a distinction between testing individual transactions and testing a flow of transactions, but in practice, it proves to be hard @@ -68,10 +64,8 @@ We will call them *ledger backends* throughout the rest of the section: It is a cluster of three `cardano-node` instances that potentially could support all Cardano features, including staking and governance. - The main downside of a privnet is that testing time is significantly bigger - (minutes not seconds even for simple tests). - So it's practically impossible to have a fresh network for every test case - but rather for the whole test suite run. + The main downside of a privnet is that testing time is significantly bigger and since spawning a testnet is a time-consuming operation, it's practically impossible to have a fresh network for every test case + but rather we prefer single testnet for the whole test suite run. @@ -82,8 +76,6 @@ We will call them *ledger backends* throughout the rest of the section: Fortunately, you can switch easily between two backends with unified testing. - TODO: add more information on how CLB/privnet differ. - Now that we know what the two backends available are, @@ -110,7 +102,7 @@ Let's run through an example test suite to get the idea and figure out its detai ## Testing placing a bet -You can find the entire code for this example [here](https://github.com/geniusyield/atlas/blob/main/tests-unified/GeniusYield/Test/Unified/BetRef/). +You can find the entire code for this example [here](https://github.com/geniusyield/atlas-examples/tree/main/bet-ref/tests). Mind you we are using [`tasty`](https://hackage.haskell.org/package/tasty) to write tests. @@ -196,7 +188,7 @@ Let's start with the runner to test `placeBet` operation. We won't see anything new here. It just uses `asUser action` we just learned to run the operation. We need values of all arguments that our operation takes. We cannot know them, so we just take all of them as arguments to the runner itself, except the address as -it can be obtained using `ownAddresses` function. This function gives back all +it can be obtained using [`ownAddresses`](https://haddock.atlas-app.io/GeniusYield-TxBuilder-Class.html#v:ownAddresses) function. This function gives back all the addresses of the wallet (`User`) that we provide to `asUser`. Once we get the result of the operation, we can build, sign, and submit a transaction. Here, again, the wallet we specified to `asUser` action is used to sign it @@ -321,7 +313,7 @@ firstBetTest betUntil betReveal betStep dat bet (testWallets -> ws@Wallets{w1}) void $ runPlaceBet refScript brp dat bet Nothing w1 ``` -The code almost verbatim repeats what we just said using the function `withWalletBalancesCheckSimple`[^1]. +The code almost verbatim repeats what we just said using the function [`withWalletBalancesCheckSimple`](https://haddock.atlas-app.io/GeniusYield-Test-FeeTracker.html#v:withWalletBalancesCheckSimple)[^1]. It allows checking the change of wallet's balance with no caring about transaction and storage fees (the latter is also known as minimal ADA - the number of coins that should accompany Cardano native tokens). This convenience is possible because Atlas manages its own record of @@ -539,7 +531,7 @@ placeBetTests setup = testGroup "Place bet" This section concludes our journey to testing dApps with Atlas. -[^1]: If you were to have fine-grained control over balance change, use `withWalletBalancesCheck` instead. +[^1]: If you were to have fine-grained control over balance change, use [`withWalletBalancesCheck`](https://haddock.atlas-app.io/GeniusYield-Test-Utils.html#v:withWalletBalancesCheck) instead. [^2]: To convey the message better, we have a defined [`(:=)`](https://haddock.atlas-app.io/GeniusYield-Test-Utils.html#v::-61-) pattern synonym: