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

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

@@ -1,4 +1,52 @@
 # 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
+
+* ensure mutable types (ARC4 tuple, array and structs) have their changes propagated back to container-like types (global/local state, boxes, ARC4 mutable types) (#14) ([`1f1f2ea`](https://github.com/algorandfoundation/algorand-python-testing/commit/1f1f2ea43a2f4f906cbcd5709b8e86b5c1f2bc63))
+
+  * fix: add default __eq__ implementation for ARC4 types
+
+  * fix: ensure mutable types (ARC4 tuple, array and structs) have their changes propagated back to container-like types (global/local state, boxes, ARC4 mutable types)
+
+  * feat: add __str__ and __repr__ implementations for ARC4 types
+
+  * refactor: make ARC4 type_info private
+
+  * refactor: make ARC4 struct inherit _ABIEncoded
+
+  * refactor: removing get_app_for_contract; expanding get_app; parsing on_complete
+
 ## v0.3.0-beta.4 (2024-08-21)
 
 ### Feature

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: algorand-python-testing
-Version: 0.3.0b4
+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.0b4 → 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.0b4 → 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.0b4 → 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)
+```