algorand-python-testing 0.3.0b5__tar.gz → 0.3.0b6__tar.gz

{algorand_python_testing-0.3.0b5 → algorand_python_testing-0.3.0b6}/CHANGELOG.md

@@ -1,4 +1,34 @@
 # CHANGELOG
+## v0.3.0-beta.6 (2024-08-21)
+
+### Documentation
+
+* documentation for initial stable release of `algorand-python-testing` (#8) ([`9d97d0d`](https://github.com/algorandfoundation/algorand-python-testing/commit/9d97d0de5ff9897e642ec3f11a186f2fb95375bb))
+
+  * docs: wip
+
+  * chore: refresh pyproject
+
+  * docs: refining docs (wip)
+
+  * chore: integrating doctests
+
+  * docs: revamping docs with latest features
+
+  * docs: minor consistency with main readme; patching doctests
+
+  * docs: removing the box from examples
+
+  * docs: refine op codes section
+
+  * chore: merge conflicts
+
+  * chore: apply suggestions from code review
+
+  Co-authored-by: Daniel McGregor <daniel.mcgregor@makerx.com.au>
+
+  * docs: addressing docs pr comments
+
 ## v0.3.0-beta.5 (2024-08-21)
 
 ### Fix

{algorand_python_testing-0.3.0b5 → algorand_python_testing-0.3.0b6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: algorand-python-testing
-Version: 0.3.0b5
+Version: 0.3.0b6
 Summary: Algorand Python testing library
 Project-URL: Documentation, https://github.com/algorandfoundation/puya/tree/main/algopy_testing#README.md
 Project-URL: Issues, https://github.com/algorandfoundation/puya/issues
@@ -57,8 +57,15 @@ Alternatively, if you want to start from scratch:
     from your_contract import YourContract
 
     def test_your_contract():
-    with algopy_testing_context() as ctx:
-    contract = YourContract() # Your test code here
+        # Arrange
+        contract = YourContract()
+        expected_result = ... # Your expected result here
+
+        # Act
+        result = contract.your_method()  # Your test code here
+
+        # Assert
+        assert result == expected_result
     ```
 
 5. Run your tests using your preferred Python testing framework (e.g., pytest, unittest)

{algorand_python_testing-0.3.0b5 → algorand_python_testing-0.3.0b6}/README.md

@@ -34,8 +34,15 @@ Alternatively, if you want to start from scratch:
     from your_contract import YourContract
 
     def test_your_contract():
-    with algopy_testing_context() as ctx:
-    contract = YourContract() # Your test code here
+        # Arrange
+        contract = YourContract()
+        expected_result = ... # Your expected result here
+
+        # Act
+        result = contract.your_method()  # Your test code here
+
+        # Assert
+        assert result == expected_result
     ```
 
 5. Run your tests using your preferred Python testing framework (e.g., pytest, unittest)

{algorand_python_testing-0.3.0b5 → algorand_python_testing-0.3.0b6}/docs/_static/custom.css

@@ -2,7 +2,8 @@
  Hide the first element of attribute like items as algopy stubs are more like interfaces and as such
  should not indicate a specific "value" for variables
  */
-.py.data,.py.attribute {
+.py.data,
+.py.attribute {
     dd p:first-child {
         display: none;
     }

algorand_python_testing-0.3.0b6/docs/algopy.md

@@ -0,0 +1,9 @@
+# Algorand Python
+
+Algorand Python is a partial implementation of the Python programming language that runs on the AVM. It includes a statically typed framework for development of Algorand smart contracts and logic signatures, with Pythonic interfaces to underlying AVM functionality that works with standard Python tooling.
+
+Algorand Python is compiled for execution on the AVM by PuyaPy, an optimising compiler that ensures the resulting AVM bytecode execution semantics that match the given Python code. PuyaPy produces output that is directly compatible with [AlgoKit typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to make deployment and calling easy.
+
+## Quick start
+
+To get started refer to the [official documentation](https://algorandfoundation.github.io/puya).

algorand_python_testing-0.3.0b6/docs/api.md

@@ -0,0 +1,14 @@
+# API Reference
+
+```{autodoc2-summary}
+:renderer: myst
+
+algopy_testing.AlgopyTestContext
+algopy_testing.LedgerContext
+algopy_testing.TransactionContext
+algopy_testing.AVMValueGenerator
+algopy_testing.TxnValueGenerator
+algopy_testing.ARC4ValueGenerator
+```
+
+> TODO: 1.0 Restructure algopy_testing index file once refactoring changes are merged

{algorand_python_testing-0.3.0b5 → algorand_python_testing-0.3.0b6}/docs/conf.py

@@ -11,6 +11,7 @@ project = "Algorand Python Testing"
 copyright = "2024, Algorand Foundation"  # noqa: A001
 author = "Algorand Foundation"
 
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -19,6 +20,9 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "myst_parser",
+    "autodoc2",
+    "sphinx.ext.doctest",
+    "sphinxmermaid",
 ]
 
 templates_path = ["_templates"]
@@ -42,7 +46,6 @@ nitpick_ignore_regex = [
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
 html_theme = "furo"
 html_static_path = ["_static"]
 html_css_files = [
@@ -52,7 +55,28 @@ html_css_files = [
 python_maximum_signature_line_length = 80
 
 # -- Options for myst ---
-myst_enable_extensions = [
-    "colon_fence",
-    "fieldlist",
+myst_enable_extensions = ["colon_fence", "fieldlist"]
+
+# -- Options for autodoc2
+autodoc2_packages = [
+    {
+        "path": "../src/algopy_testing",
+        "auto_mode": False,
+    },
+]
+autodoc2_render_plugin = "myst"
+autodoc2_hidden_objects = [
+    "dunder",
+    "private",
+    "undoc",
 ]
+add_module_names = False
+autodoc2_index_template = None
+
+# -- Options for doctest --
+doctest_test_doctest_blocks = "default"
+
+# -- Options for mermaid --
+sphinxmermaid_mermaid_init = {
+    "theme": "dark",
+}

algorand_python_testing-0.3.0b6/docs/coverage.md

@@ -0,0 +1,162 @@
+# Coverage
+
+See which `algorand-python` stubs are implemented by the `algorand-python-testing` library. See the [Concepts](testing-guide/concepts.md#types-of-algopy-stub-implementations) section for more details on the implementation categories.
+
+Based on the definitions provided and the implementation details in the `src` directory, here is the classification for the abstractions outlined in the table under the `Name` column:
+
+| Name                                        | Implementation type |
+| ------------------------------------------- | ------------------- |
+| algopy.Account                              | Emulated            |
+| algopy.Application                          | Emulated            |
+| algopy.Asset                                | Emulated            |
+| algopy.BigUInt                              | Native              |
+| algopy.Box                                  | Emulated            |
+| algopy.BoxMap                               | Emulated            |
+| algopy.BoxRef                               | Emulated            |
+| algopy.Bytes                                | Native              |
+| algopy.BytesBacked                          | Native              |
+| algopy.CompiledContract                     | Mockable            |
+| algopy.CompiledLogicSig                     | Mockable            |
+| algopy.Contract                             | Emulated            |
+| algopy.Global                               | Emulated            |
+| algopy.GlobalState                          | Emulated            |
+| algopy.LocalState                           | Emulated            |
+| algopy.LogicSig                             | Emulated            |
+| algopy.OnCompleteAction                     | Native              |
+| algopy.OpUpFeeSource                        | Native              |
+| algopy.StateTotals                          | Emulated            |
+| algopy.String                               | Native              |
+| algopy.TemplateVar                          | Emulated            |
+| algopy.TransactionType                      | Native              |
+| algopy.Txn                                  | Emulated            |
+| algopy.UInt64                               | Native              |
+| algopy.compile_contract                     | Mockable            |
+| algopy.compile_logicsig                     | Mockable            |
+| algopy.ensure_budget                        | Emulated            |
+| algopy.log                                  | Emulated            |
+| algopy.logicsig                             | Emulated            |
+| algopy.subroutine                           | Native              |
+| algopy.uenumerate                           | Native              |
+| algopy.urange                               | Native              |
+| algopy.arc4.ARC4Client                      | Emulated            |
+| algopy.arc4.ARC4Contract                    | Emulated            |
+| algopy.arc4.Address                         | Native              |
+| algopy.arc4.BigUFixedNxM                    | Native              |
+| algopy.arc4.BigUIntN                        | Native              |
+| algopy.arc4.Bool                            | Native              |
+| algopy.arc4.Byte                            | Native              |
+| algopy.arc4.DynamicArray                    | Native              |
+| algopy.arc4.DynamicBytes                    | Native              |
+| algopy.arc4.StaticArray                     | Native              |
+| algopy.arc4.String                          | Native              |
+| algopy.arc4.Struct                          | Native              |
+| algopy.arc4.Tuple                           | Native              |
+| algopy.arc4.UFixedNxM                       | Native              |
+| algopy.arc4.UInt128                         | Native              |
+| algopy.arc4.UInt16                          | Native              |
+| algopy.arc4.UInt256                         | Native              |
+| algopy.arc4.UInt32                          | Native              |
+| algopy.arc4.UInt512                         | Native              |
+| algopy.arc4.UInt64                          | Native              |
+| algopy.arc4.UInt8                           | Native              |
+| algopy.arc4.UIntN                           | Native              |
+| algopy.arc4.abimethod                       | Emulated            |
+| algopy.arc4.arc4_signature                  | Native              |
+| algopy.arc4.baremethod                      | Emulated            |
+| algopy.arc4.emit                            | Emulated            |
+| algopy.arc4.abi_call                        | Mockable            |
+| algopy.arc4.arc4_create                     | Mockable            |
+| algopy.arc4.arc4_update                     | Mockable            |
+| algopy.gtxn.ApplicationCallTransaction      | Emulated            |
+| algopy.gtxn.AssetConfigTransaction          | Emulated            |
+| algopy.gtxn.AssetFreezeTransaction          | Emulated            |
+| algopy.gtxn.AssetTransferTransaction        | Emulated            |
+| algopy.gtxn.KeyRegistrationTransaction      | Emulated            |
+| algopy.gtxn.PaymentTransaction              | Emulated            |
+| algopy.gtxn.Transaction                     | Emulated            |
+| algopy.gtxn.TransactionBase                 | Emulated            |
+| algopy.itxn.ApplicationCall                 | Emulated            |
+| algopy.itxn.ApplicationCallInnerTransaction | Emulated            |
+| algopy.itxn.AssetConfig                     | Emulated            |
+| algopy.itxn.AssetConfigInnerTransaction     | Emulated            |
+| algopy.itxn.AssetFreeze                     | Emulated            |
+| algopy.itxn.AssetFreezeInnerTransaction     | Emulated            |
+| algopy.itxn.AssetTransfer                   | Emulated            |
+| algopy.itxn.AssetTransferInnerTransaction   | Emulated            |
+| algopy.itxn.InnerTransaction                | Emulated            |
+| algopy.itxn.InnerTransactionResult          | Emulated            |
+| algopy.itxn.KeyRegistration                 | Emulated            |
+| algopy.itxn.KeyRegistrationInnerTransaction | Emulated            |
+| algopy.itxn.Payment                         | Emulated            |
+| algopy.itxn.PaymentInnerTransaction         | Emulated            |
+| algopy.itxn.submit_txns                     | Emulated            |
+| algopy.op.Base64                            | Native              |
+| algopy.op.EC                                | Native              |
+| algopy.op.ECDSA                             | Native              |
+| algopy.op.JsonRef                           | Native              |
+| algopy.op.addw                              | Native              |
+| algopy.op.arg                               | Emulated            |
+| algopy.op.base64_decode                     | Native              |
+| algopy.op.bitlen                            | Native              |
+| algopy.op.bsqrt                             | Native              |
+| algopy.op.btoi                              | Native              |
+| algopy.op.bzero                             | Native              |
+| algopy.op.concat                            | Native              |
+| algopy.op.divmodw                           | Native              |
+| algopy.op.divw                              | Native              |
+| algopy.op.ecdsa_pk_decompress               | Native              |
+| algopy.op.ecdsa_pk_recover                  | Native              |
+| algopy.op.ecdsa_verify                      | Native              |
+| algopy.op.ed25519verify                     | Native              |
+| algopy.op.ed25519verify_bare                | Native              |
+| algopy.op.err                               | Native              |
+| algopy.op.exit                              | Native              |
+| algopy.op.exp                               | Native              |
+| algopy.op.expw                              | Native              |
+| algopy.op.extract                           | Native              |
+| algopy.op.extract_uint16                    | Native              |
+| algopy.op.extract_uint32                    | Native              |
+| algopy.op.extract_uint64                    | Native              |
+| algopy.op.getbit                            | Native              |
+| algopy.op.getbyte                           | Native              |
+| algopy.op.itob                              | Native              |
+| algopy.op.keccak256                         | Native              |
+| algopy.op.mulw                              | Native              |
+| algopy.op.replace                           | Native              |
+| algopy.op.select_bytes                      | Native              |
+| algopy.op.select_uint64                     | Native              |
+| algopy.op.setbit_bytes                      | Native              |
+| algopy.op.setbit_uint64                     | Native              |
+| algopy.op.setbyte                           | Native              |
+| algopy.op.sha256                            | Native              |
+| algopy.op.sha3_256                          | Native              |
+| algopy.op.sha512_256                        | Native              |
+| algopy.op.shl                               | Native              |
+| algopy.op.shr                               | Native              |
+| algopy.op.sqrt                              | Native              |
+| algopy.op.substring                         | Native              |
+| algopy.op.AppGlobal                         | Emulated            |
+| algopy.op.AppLocal                          | Emulated            |
+| algopy.op.AppParamsGet                      | Emulated            |
+| algopy.op.AssetHoldingGet                   | Emulated            |
+| algopy.op.AssetParamsGet                    | Emulated            |
+| algopy.op.Block                             | Emulated            |
+| algopy.op.Box                               | Emulated            |
+| algopy.op.GITxn                             | Emulated            |
+| algopy.op.GTxn                              | Emulated            |
+| algopy.op.Global                            | Emulated            |
+| algopy.op.ITxn                              | Emulated            |
+| algopy.op.ITxnCreate                        | Emulated            |
+| algopy.op.Scratch                           | Emulated            |
+| algopy.op.Txn                               | Emulated            |
+| algopy.op.app_opted_in                      | Emulated            |
+| algopy.op.balance                           | Emulated            |
+| algopy.op.gaid                              | Emulated            |
+| algopy.op.gload_bytes                       | Emulated            |
+| algopy.op.gload_uint64                      | Emulated            |
+| algopy.op.min_balance                       | Emulated            |
+| algopy.op.AcctParamsGet                     | Emulated            |
+| algopy.op.EllipticCurve                     | Mockable            |
+| algopy.op.VrfVerify                         | Mockable            |
+| algopy.op.vrf_verify                        | Mockable            |
+

algorand_python_testing-0.3.0b6/docs/examples.md

@@ -0,0 +1,13 @@
+# Examples
+
+Below is a showcase of various examples of unit testing real and sample Algorand Python smart contracts using `algorand-python-testing`.
+
+| Contract Name       | Test File                                                                                                                                 | Key Features Demonstrated                                                                                                                                                                                        | Test versions of Algopy Abstractions used                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Auction             | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/auction/test_contract.py)             | - Use of algopy_testing_context<br>- Mocking of global state and transaction fields<br>- Testing of ARC4 contract methods<br>- Emulation of asset creation and transfers<br>- Verification of inner transactions | - **ARC4Contract**<br>- **Global**<br>- **Txn**<br>- **Asset**<br>- **Account**<br>- **LocalState** |
+| Proof of Attendance | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/proof_of_attendance/test_contract.py) | - Creation and management of dummy assets<br>- Testing of box storage operations<br>- Verification of inner transactions for asset transfers<br>- Use of any\_\* methods for generating test data                | - **ARC4Contract**<br>- **Box**<br>- **BoxMap**<br>- **Asset**<br>- **Account**<br>- **op**         |
+| Simple Voting       | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/simple_voting/test_contract.py)       | - Testing of global and local state operations<br>- Verification of transaction group operations<br>- Mocking of payment transactions                                                                            | - **Contract**<br>- **GlobalState**<br>- **LocalState**<br>- **Txn**<br>- **op.GTxn**               |
+| ZK Whitelist        | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/zk_whitelist/test_contract.py)        | - Testing of zero-knowledge proof verification<br>- Mocking of external application calls<br>- Use of ARC4 types and methods                                                                                     | - **ARC4Contract**<br>- **arc4 types**<br>- **LocalState**<br>- **Global**<br>- **Txn**             |
+| HTLC LogicSig       | [test_signature.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/htlc_logicsig/test_signature.py)     | - Testing of LogicSig contracts<br>- Verification of time-based conditions<br>- Mocking of transaction parameters                                                                                                | - **logicsig**<br>- **Account**<br>- **Txn**<br>- **Global**<br>- **op**                            |
+| Marketplace         | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/marketplace/test_contract.py)         | - Testing of complex marketplace operations<br>- Use of BoxMap for listings<br>- Testing of asset transfers and payments                                                                                         | - **ARC4Contract**<br>- **BoxMap**<br>- **Asset**<br>- **arc4 types**<br>- **Global**<br>- **Txn**  |
+| Scratch Storage     | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/scratch_storage/test_contract.py)     | - Testing of scratch space usage<br>- Verification of scratch slot values                                                                                                                                        | - **ARC4Contract**<br>- **Contract**<br>- **op**                                                    |

algorand_python_testing-0.3.0b6/docs/glossary.md

@@ -0,0 +1,8 @@
+# Glossary
+
+| Term                                                                                                                                       | Definition                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [**Test Context**](testing-guide/concepts.md#test-context)                                                                                 | A context manager that provides a simulated Algorand environment for testing Python smart contracts.                                                                                                                               |
+| [**Algorand Virtual Machine (AVM)**](https://developer.algorand.org/docs/get-details/dapps/avm/)                                           | The AVM is the runtime environment for Algorand smart contracts.                                                                                                                                                                   |
+| [**Operational codes**](https://developer.algorand.org/docs/get-details/dapps/avm/teal/opcodes/?from_query=OPcodes#template-modal-overlay) | AVM instructions that are executed directly by the AVM, provided by `algopy` stubs and emulated/implemented or mocked by `algorand-python-testing`.                                                                                |
+| [**Value generators**](testing-guide/concepts.md#value-generators)                                                                         | Helper methods that generate randomized values for testing when the value of the tested type is not needed. Represented by instance methods on the context manager, prefixed with `any_*` (or `arc.any_*` in case of ARC 4 types). |

algorand_python_testing-0.3.0b6/docs/index.md

@@ -0,0 +1,198 @@
+# Algorand Python Testing
+
+[![docs-repository](https://img.shields.io/badge/url-repository-74dfdc?logo=github&style=flat.svg)](https://github.com/algorandfoundation/algorand-python-testing/)
+[![learn-AlgoKit](https://img.shields.io/badge/learn-AlgoKit-74dfdc?logo=algorand&mac=flat.svg)](https://developer.algorand.org/algokit/)
+[![github-stars](https://img.shields.io/github/stars/algorandfoundation/algorand-python-testing?color=74dfdc&logo=star&style=flat)](https://github.com/algorandfoundation/algorand-python-testing)
+[![visitor-badge](https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Falgorandfoundation%2Falgorand-python-testing&countColor=%2374dfdc&style=flat)](https://developer.algorand.org/algokit/)
+
+`algorand-python-testing` is a companion package to [Algorand Python](https://github.com/algorandfoundation/puya) that enables efficient unit testing of Algorand Python smart contracts in an offline environment. This package emulates key AVM behaviors without requiring a network connection, offering fast and reliable testing capabilities with a familiar Pythonic interface.
+
+The `algorand-python-testing` package provides:
+
+-   A simple interface for fast and reliable unit testing
+-   An offline testing environment that simulates core AVM functionality
+-   A familiar Pythonic experience, compatible with testing frameworks like [pytest](https://docs.pytest.org/en/latest/), [unittest](https://docs.python.org/3/library/unittest.html), and [hypothesis](https://hypothesis.readthedocs.io/en/latest/)
+
+```{testsetup}
+import algopy
+import algopy_testing
+from algopy_testing import algopy_testing_context
+
+# Create the context manager for snippets below
+ctx_manager = algopy_testing_context()
+
+# Enter the context
+context = ctx_manager.__enter__()
+```
+
+## Quick Start
+
+`algopy` is a prerequisite for `algorand-python-testing`, providing stubs and type annotations for Algorand Python syntax. It enhances code completion and type checking when writing smart contracts. Note that this code isn't directly executable in standard Python interpreters; it's compiled by `puya` into TEAL for Algorand Network deployment.
+
+Traditionally, testing Algorand smart contracts involved deployment on sandboxed networks and interacting with live instances. While robust, this approach can be inefficient and lacks versatility for testing Algorand Python code.
+
+Enter `algorand-python-testing`: it leverages Python's rich testing ecosystem for unit testing without network deployment. This enables rapid iteration and granular logic testing.
+
+> **NOTE**: While `algorand-python-testing` offers valuable unit testing capabilities, it's not a replacement for comprehensive testing. Use it alongside other test types, particularly those running against the actual Algorand Network, for thorough contract validation.
+
+### Prerequisites
+
+-   Python 3.12 or later
+-   [Algorand Python](https://github.com/algorandfoundation/puya)
+
+### Installation
+
+`algorand-python-testing` is distributed via [PyPI](https://pypi.org/project/algorand-python-testing/). Install the package using `pip`:
+
+```bash
+pip install algorand-python-testing
+```
+
+or using `poetry`:
+
+```bash
+poetry add algorand-python-testing
+```
+
+### Testing your first contract
+
+Let's write a simple contract and test it using the `algorand-python-testing` framework.
+
+#### Contract Definition
+
+```{testcode}
+import algopy
+from algopy import arc4
+
+class VotingContract(algopy.ARC4Contract):
+    def __init__(self) -> None:
+        self.topic = algopy.GlobalState(algopy.Bytes(b"default_topic"), key="topic", description="Voting topic")
+        self.votes = algopy.GlobalState(
+            algopy.UInt64(0),
+            key="votes",
+            description="Votes for the option",
+        )
+        self.voted = algopy.LocalState(algopy.UInt64, key="voted", description="Tracks if an account has voted")
+
+    @arc4.abimethod
+    def set_topic(self, topic: arc4.String) -> None:
+        self.topic.value = topic.bytes
+
+    @arc4.abimethod
+    def vote(self, pay: algopy.gtxn.PaymentTransaction) -> arc4.Bool:
+        assert algopy.op.Global.group_size == algopy.UInt64(2), "Expected 2 transactions"
+        assert pay.amount == algopy.UInt64(10_000), "Incorrect payment amount"
+        assert pay.sender == algopy.Txn.sender, "Payment sender must match transaction sender"
+
+        _value, exists = self.voted.maybe(algopy.Txn.sender)
+        if exists:
+            return arc4.Bool(False)  # Already voted
+        self.votes.value += algopy.UInt64(1)
+        self.voted[algopy.Txn.sender] = algopy.UInt64(1)
+        return arc4.Bool(True)
+
+    @arc4.abimethod(readonly=True)
+    def get_votes(self) -> arc4.UInt64:
+        return arc4.UInt64(self.votes.value)
+
+    def clear_state_program(self) -> bool:
+        return True
+```
+
+#### Test Definition
+
+```{testcode}
+from collections.abc import Generator
+import pytest
+from algopy_testing import AlgopyTestContext, algopy_testing_context
+from algopy import arc4
+
+# Create a test context
+with algopy_testing_context() as context:
+
+    # Initialize the contract
+    contract = VotingContract()
+
+    # Test vote function
+    voter = context.default_sender
+    payment = context.any.txn.payment(
+        sender=voter,
+        amount=algopy.UInt64(10_000),
+    )
+
+    result = contract.vote(payment)
+    print(f"Vote result: {result.native}")
+    print(f"Total votes: {contract.votes.value}")
+    print(f"Voter {voter} voted: {contract.voted[voter]}")
+
+    # Test set_topic function
+    new_topic = context.any.arc4.string(10)
+    contract.set_topic(new_topic)
+    print(f"New topic: {new_topic.native}")
+    print(f"Contract topic: {contract.topic.value}")
+
+    # Test get_votes function
+    contract.votes.value = algopy.UInt64(5)
+    votes = contract.get_votes()
+    print(f"Current votes: {votes.native}")
+```
+
+```{testoutput}
+:hide:
+
+Vote result: True
+Total votes: 1
+Voter ... voted: 1
+New topic: ...
+Contract topic: ...
+Current votes: 5
+```
+
+This example demonstrates key aspects of testing with `algorand-python-testing` for ARC4-based contracts:
+
+1. ARC4 Contract Features:
+
+    - Use of `algopy.ARC4Contract` as the base class for the contract.
+    - ABI methods defined using the `@arc4.abimethod` decorator.
+    - Use of ARC4-specific types like `arc4.String`, `arc4.Bool`, and `arc4.UInt64`.
+    - Readonly method annotation with `@arc4.abimethod(readonly=True)`.
+
+2. Testing ARC4 Contracts:
+
+    - Creation of an `ARC4Contract` instance within the test context.
+    - Use of `context.any.arc4` for generating ARC4-specific random test data.
+    - Direct invocation of ABI methods on the contract instance.
+
+3. Transaction Handling:
+
+    - Use of `context.any.txn` to create test transactions.
+    - Passing transaction objects as parameters to contract methods.
+
+4. State Verification:
+    - Checking global and local state changes after method execution.
+    - Verifying return values from ABI methods using ARC4-specific types.
+
+> **NOTE**: Thorough testing is crucial in smart contract development due to their immutable nature post-deployment. Comprehensive unit and integration tests ensure contract validity and reliability. Optimizing for efficiency can significantly improve user experience by reducing transaction fees and simplifying interactions. Investing in robust testing and optimization practices is crucial and offers many benefits in the long run.
+
+### Next steps
+
+To dig deeper into the capabilities of `algorand-python-testing`, continue with the following sections.
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+hidden: true
+---
+
+testing-guide/index
+examples
+coverage
+glossary
+api
+algopy
+```
+
+```{testcleanup}
+ctx_manager.__exit__(None, None, None)
+```

algorand_python_testing-0.3.0b6/docs/testing-guide/arc4-types.md

@@ -0,0 +1,97 @@
+# ARC4 Types
+
+These types are available under the `algopy.arc4` namespace. Refer to the [ARC4 specification](https://arc.algorand.foundation/ARCs/arc-0004) for more details on the spec.
+
+```{hint}
+Test context manager provides _value generators_ for ARC4 types. To access their _value generators_, use `{context_instance}.any.arc4` property. See more examples below.
+```
+
+```{note}
+For all `algopy.arc4` types with and without respective _value generator_, instantiation can be performed directly. If you have a suggestion for a new _value generator_ implementation, please open an issue in the [`algorand-python-testing`](https://github.com/algorandfoundation/algorand-python-testing) repository or contribute by following the [contribution guide](https://github.com/algorandfoundation/algorand-python-testing/blob/main/CONTRIBUTING.md).
+```
+
+```{testsetup}
+import algopy
+import algopy_testing
+from algopy_testing import algopy_testing_context
+
+# Create the context manager for snippets below
+ctx_manager = algopy_testing_context()
+
+# Enter the context
+context = ctx_manager.__enter__()
+```
+
+## Unsigned Integers
+
+```{testcode}
+from algopy import arc4
+
+# Integer types
+uint8_value = arc4.UInt8(255)
+uint16_value = arc4.UInt16(65535)
+uint32_value = arc4.UInt32(4294967295)
+uint64_value = arc4.UInt64(18446744073709551615)
+
+... # instantiate test context
+# Generate a random unsigned arc4 integer with default range
+uint8 = context.any.arc4.uint8()
+uint16 = context.any.arc4.uint16()
+uint32 = context.any.arc4.uint32()
+uint64 = context.any.arc4.uint64()
+biguint128 = context.any.arc4.biguint128()
+biguint256 = context.any.arc4.biguint256()
+biguint512 = context.any.arc4.biguint512()
+
+# Generate a random unsigned arc4 integer with specified range
+uint8_custom = context.any.arc4.uint8(min_value=10, max_value=100)
+uint16_custom = context.any.arc4.uint16(min_value=1000, max_value=5000)
+uint32_custom = context.any.arc4.uint32(min_value=100000, max_value=1000000)
+uint64_custom = context.any.arc4.uint64(min_value=1000000000, max_value=10000000000)
+biguint128_custom = context.any.arc4.biguint128(min_value=1000000000000000, max_value=10000000000000000)
+biguint256_custom = context.any.arc4.biguint256(min_value=1000000000000000000000000, max_value=10000000000000000000000000)
+biguint512_custom = context.any.arc4.biguint512(min_value=10000000000000000000000000000000000, max_value=10000000000000000000000000000000000)
+```
+
+## Address
+
+```{testcode}
+from algopy import arc4
+
+# Address type
+address_value = arc4.Address("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ")
+
+# Generate a random address
+random_address = context.any.arc4.address()
+
+# Access native underlaying type
+native = random_address.native
+```
+
+## Dynamic Bytes
+
+```{testcode}
+from algopy import arc4
+
+# Dynamic byte string
+bytes_value = arc4.DynamicBytes(b"Hello, Algorand!")
+
+# Generate random dynamic bytes
+random_dynamic_bytes = context.any.arc4.dynamic_bytes(n=123) # n is the number of bits in the arc4 dynamic bytes
+```
+
+## String
+
+```{testcode}
+from algopy import arc4
+
+# UTF-8 encoded string
+string_value = arc4.String("Hello, Algorand!")
+
+# Generate random string
+random_string = context.any.arc4.string(n=12) # n is the number of bits in the arc4 string
+```
+
+```{testcleanup}
+ctx_manager.__exit__(None, None, None)
+```