diff --git a/docs/algopy.md b/docs/algopy.md index 426f3e87..c30f1922 100644 --- a/docs/algopy.md +++ b/docs/algopy.md @@ -1,9 +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 a partial implementation of the Python programming language that runs on the AVM. It includes a statically typed framework for developing Algorand smart contracts and logic signatures, with Pythonic interfaces to underlying AVM functionality that work 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. +Algorand Python is compiled for execution on the AVM by PuyaPy, an optimising compiler that ensures the resulting AVM bytecode has 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). +To get started, refer to the [official documentation](https://algorandfoundation.github.io/puya). diff --git a/docs/api.md b/docs/api.md index 8c0168af..e8488388 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,13 +1,13 @@ # API Reference -An overview of the `algorand-python-testing`'s `algopy_testing` module - covering the main classes and functions. +An overview of the `algopy_testing` module in `algorand-python-testing` library - covering the main classes and functions. ```{hint} -Spotted a typo in documentation? This project is open source, please submit an issue or a PR on [GitHub](https://github.com/algorand/algorand-python-testing). +Spotted a typo in the documentation? This project is open source; please submit an issue or a PR on [GitHub](https://github.com/algorandfoundation/algorand-python-testing). ``` ```{warning} -Note, assume `_algopy_testing` to refer to `algopy_testing` namespace in the auto-generated class documentation above. To be patched in near future. +Note: Auto-generated class documentation may reference `_algopy_testing`; these should be interpreted as the `algopy_testing` namespace. The naming discrepancy will be fixed in a future update. ``` ## Contexts diff --git a/docs/coverage.md b/docs/coverage.md index 631224de..af1d7c6f 100644 --- a/docs/coverage.md +++ b/docs/coverage.md @@ -1,9 +1,9 @@ # 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. Refer to the [`algorand-python` stubs API](api.md) for the full list of the stubs for which the `algorand-python-testing` library provides implementations referenced in the table below. +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. Refer to the [`algorand-python` stubs API](api.md) for the full list of stubs for which the `algorand-python-testing` library provides implementations referenced in the table below. | Name | Implementation type | -|---------------------------------------------|---------------------| +| ------------------------------------------- | ------------------- | | algopy.Account | Emulated | | algopy.Application | Emulated | | algopy.Asset | Emulated | @@ -158,3 +158,4 @@ See which `algorand-python` stubs are implemented by the `algorand-python-testin | algopy.op.EllipticCurve | Mockable | | algopy.op.VrfVerify | Mockable | | algopy.op.vrf_verify | Mockable | +| algopy.op.falcon_verify | Mockable | diff --git a/docs/examples.md b/docs/examples.md index 6bbebcf3..423421c4 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -5,9 +5,9 @@ Below is a showcase of various examples of unit testing real and sample Algorand | 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
- Mocking of global state and transaction fields
- Testing of ARC4 contract methods
- Emulation of asset creation and transfers
- Verification of inner transactions | - **ARC4Contract**
- **Global**
- **Txn**
- **Asset**
- **Account**
- **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
- Testing of box storage operations
- Verification of inner transactions for asset transfers
- Use of any\_\* methods for generating test data | - **ARC4Contract**
- **Box**
- **BoxMap**
- **Asset**
- **Account**
- **op** | +| 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
- Testing of box storage operations
- Verification of inner transactions for asset transfers
- Use of `any.*` methods for generating test data | - **ARC4Contract**
- **Box**
- **BoxMap**
- **Asset**
- **Account**
- **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
- Verification of transaction group operations
- Mocking of payment transactions | - **Contract**
- **GlobalState**
- **LocalState**
- **Txn**
- **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
- Mocking of external application calls
- Use of ARC4 types and methods | - **ARC4Contract**
- **arc4 types**
- **LocalState**
- **Global**
- **Txn** | +| 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
- Mocking of external application calls
- Use of ARC4 types and methods | - **ARC4Contract**
- **ARC4 types**
- **LocalState**
- **Global**
- **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
- Verification of time-based conditions
- Mocking of transaction parameters | - **logicsig**
- **Account**
- **Txn**
- **Global**
- **op** | -| Marketplace | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/marketplace/test_contract.py) | - Testing of complex marketplace operations
- Use of BoxMap for listings
- Testing of asset transfers and payments | - **ARC4Contract**
- **BoxMap**
- **Asset**
- **arc4 types**
- **Global**
- **Txn** | +| Marketplace | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/marketplace/test_contract.py) | - Testing of complex marketplace operations
- Use of BoxMap for listings
- Testing of asset transfers and payments | - **ARC4Contract**
- **BoxMap**
- **Asset**
- **ARC4 types**
- **Global**
- **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
- Verification of scratch slot values | - **ARC4Contract**
- **Contract**
- **op** | diff --git a/docs/faq.md b/docs/faq.md index dba88cd1..335eb5df 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,7 +14,7 @@ Operational Codes, or opcodes, are AVM instructions that are executed directly b ## What are Value Generators? -Value Generators are helper methods that generate randomized values for testing when the specific value of the tested type is not important. In the context of Algorand Python testing, these are represented by property on the context manager, accessed via `any.*` (or `any.arc4.*`, `any.txn.*`. in the case of ARC 4 types). To understand how to use Value Generators effectively, check out our [Value Generators section](testing-guide/concepts.md#value-generators) in the documentation. +Value Generators are helper methods that produce randomized values for testing when the exact value of a type isn't important. In Algorand Python testing these generators are exposed as properties on the test context manager and accessed via `any.*` (for example, `any.arc4.*` and `any.txn.*` for ARC4 types). To learn more, see the [Value Generators section](testing-guide/concepts.md#value-generators). ## What are the limitations of the Algorand Python Testing framework? @@ -26,7 +26,7 @@ The Algorand Python Testing framework emulates the Algorand Virtual Machine (AVM 4. Certain cryptographic operations are mocked or simplified 5. No state proof generation or verification -For scenarios where these limitations are crucial, it's recommended to pair this framework with integration testing. If you have a solid reason to justify introducing new emulated behaviour, please open an issue or contribute to the project on [Github](https://github.com/algorandfoundation/algorand-python-testing). +For scenarios where these limitations are crucial, it's recommended to pair this framework with integration testing. If you have a solid reason to justify introducing new emulated behaviour, please open an issue or contribute to the project on [GitHub](https://github.com/algorandfoundation/algorand-python-testing). ## How does balance tracking work in the testing framework? @@ -46,16 +46,16 @@ Some cryptographic operations are mocked or simplified in the framework. For a d ## Can I use this framework for security-critical validations? -While this framework is useful for unit testing and local development, it should not be the only tool used for security-critical validations or performance benchmarking. It's designed to approximate AVM behavior for common scenarios. Always complement your testing with additional integration testing options available in `algokit`, where you can test against real localnet or testnet environments. +While this framework is useful for unit testing and local development, it should not be the only tool used for security-critical validations or performance benchmarking. It's designed to approximate AVM behaviour for common scenarios. Always complement your testing with additional integration testing options available in `algokit`, where you can test against real localnet or testnet environments. ## Is there an example of how to use this framework alongside integration tests? Yes, the `algokit-python-template`, accessible via `algokit init`, provides a working example of how to structure `algorand-python-testing` along with regular integration tests against localnet. ```{hint} -An `algokit-python-template` accessible via `algokit init -t python`, provides a comprehensive and customizable working example of how to structure `algorand-python-testing` along with regular integration tests against localnet. +The `algokit-python-template`, accessible via `algokit init -t python`, provides a comprehensive and customizable working example of how to structure `algorand-python-testing` along with regular integration tests against localnet. ``` ## Is it compatible with `pytest`? -Yes, it is compatible with `pytest` and _any_ other python testing framework as its agnostic of the testing framework as long as its python. If you spot incompatibility with a certain tool, please open an issue or contribute to the project on [Github](https://github.com/algorandfoundation/algorand-python-testing). +Yes, it is compatible with `pytest` and _any_ other Python testing framework as it is agnostic of the testing framework as long as it's Python. If you spot incompatibility with a certain tool, please open an issue or contribute to the project on [GitHub](https://github.com/algorandfoundation/algorand-python-testing). diff --git a/docs/index.md b/docs/index.md index 18a963b6..7d101f13 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,7 @@ [![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. +`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 behaviours without requiring a network connection, offering fast and reliable testing capabilities with a familiar Pythonic interface. The `algorand-python-testing` package provides: @@ -160,7 +160,7 @@ This example demonstrates key aspects of testing with `algorand-python-testing` - 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. +> **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. Optimising for efficiency can significantly improve user experience by reducing transaction fees and simplifying interactions. Investing in robust testing and optimisation practices is crucial and offers many benefits in the long run. ### Next steps diff --git a/docs/testing-guide/arc4-types.md b/docs/testing-guide/arc4-types.md index 434d05e0..b1d6ca0d 100644 --- a/docs/testing-guide/arc4-types.md +++ b/docs/testing-guide/arc4-types.md @@ -1,9 +1,9 @@ # 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. +These types are available under the `algopy.arc4` namespace. Refer to the [ARC4 specification](https://dev.algorand.co/arc-standards/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. +The test context manager provides _value generators_ for ARC4 types. To access the _value generators_, use `{context_instance}.any.arc4` property. See more examples below. ``` ```{note} @@ -63,7 +63,7 @@ address_value = arc4.Address("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA # Generate a random address random_address = context.any.arc4.address() -# Access native underlaying type +# Access native underlying type native = random_address.native ``` @@ -76,7 +76,7 @@ from algopy import arc4 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 +random_dynamic_bytes = context.any.arc4.dynamic_bytes(n=123) # n is the number of bits in the ARC4 dynamic bytes ``` ## String @@ -88,7 +88,7 @@ from algopy import arc4 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 +random_string = context.any.arc4.string(n=12) # n is the number of bits in the ARC4 string ``` ```{testcleanup} diff --git a/docs/testing-guide/avm-types.md b/docs/testing-guide/avm-types.md index 6a6c78d1..693a309d 100644 --- a/docs/testing-guide/avm-types.md +++ b/docs/testing-guide/avm-types.md @@ -3,7 +3,7 @@ These types are available directly under the `algopy` namespace. They represent the basic AVM primitive types and can be instantiated directly or via _value generators_: ```{note} -For 'primitive `algopy` types such as `Account`, `Application`, `Asset`, `UInt64`, `BigUint`, `Bytes`, `Sting` 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). +For primitive `algopy` types such as `Account`, `Application`, `Asset`, `UInt64`, `BigUint`, `Bytes`, and `String`, instantiation can be performed directly, with or without a corresponding _value generator_. 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} diff --git a/docs/testing-guide/concepts.md b/docs/testing-guide/concepts.md index 2f5c9b54..60772f8b 100644 --- a/docs/testing-guide/concepts.md +++ b/docs/testing-guide/concepts.md @@ -4,7 +4,7 @@ The following sections provide an overview of key concepts and features in the A ## Test Context -The main abstraction for interacting with the testing framework is the [`AlgopyTestContext`](../api-context.md#algopy_testing.AlgopyTestContext). It creates an emulated Algorand environment that closely mimics AVM behavior relevant to unit testing the contracts and provides a Pythonic interface for interacting with the emulated environment. +The main abstraction for interacting with the testing framework is the [`AlgopyTestContext`](#_algopy_testing.context.AlgopyTestContext). It creates an emulated Algorand environment that closely mimics AVM behaviour relevant to unit testing contracts and provides a Pythonic interface for interacting with the emulated environment. ```python from algopy_testing import algopy_testing_context @@ -24,15 +24,18 @@ The context manager interface exposes three main properties: 3. `any`: An instance of `AlgopyValueGenerator` for generating randomized test data. For detailed method signatures, parameters, and return types, refer to the following API sections: -- [`algopy_testing.LedgerContext`](../api.md) -- [`algopy_testing.TransactionContext`](../api.md) -- [`algopy_testing.AVMValueGenerator`, `algopy_testing.TxnValueGenerator`, `algopy_testing.ARC4ValueGenerator`](../api.md) + +- [`algopy_testing.LedgerContext`](#_algopy_testing.context_helpers.ledger_context.LedgerContext) +- [`algopy_testing.TransactionContext`](#_algopy_testing.context_helpers.txn_context.TransactionContext) +- [`algopy_testing.AVMValueGenerator`](#_algopy_testing.value_generators.avm.AVMValueGenerator) +- [`algopy_testing.TxnValueGenerator`](#_algopy_testing.value_generators.txn.TxnValueGenerator) +- [`algopy_testing.ARC4ValueGenerator`](#_algopy_testing.value_generators.arc4.ARC4ValueGenerator) The `any` property provides access to different value generators: -- `AVMValueGenerator`: Base abstractions for AVM types. All methods are available directly on the instance returned from `any`. -- `TxnValueGenerator`: Accessible via `any.txn`, for transaction-related data. -- `ARC4ValueGenerator`: Accessible via `any.arc4`, for ARC4 type data. +- `AVMValueGenerator`: Base abstractions for AVM types. All methods are available directly on the instance returned from `any`. +- `TxnValueGenerator`: Accessible via `any.txn`, for transaction-related data. +- `ARC4ValueGenerator`: Accessible via `any.arc4`, for ARC4 type data. These generators allow creation of constrained random values for various AVM entities (accounts, assets, applications, etc.) when specific values are not required. @@ -50,9 +53,8 @@ As explained in the [introduction](index.md), `algorand-python-testing` _injects 1. **Native**: Fully matches AVM computation in Python. For example, `algopy.op.sha256` and other cryptographic operations behave identically in AVM and unit tests. This implies that the majority of opcodes that are 'pure' functions in AVM also have a native Python implementation provided by this package. These abstractions and opcodes can be used within and outside of the testing context. -2. **Emulated**: Uses `AlgopyTestContext` to mimic AVM behavior. For example, `Box.put` on an `algopy.Box` within a test context stores data in the test manager, not the real Algorand network, but provides the same interface. +2. **Emulated**: Uses `AlgopyTestContext` to mimic AVM behaviour. For example, `Box.put` on an `algopy.Box` within a test context stores data in the test manager, not the real Algorand network, but provides the same interface. -3. **Mockable**: Not implemented, but can be mocked or patched. For example, `algopy.abi_call` can be mocked to return specific values or behaviors; otherwise, it raises a `NotImplementedError`. This category covers cases where native or emulated implementation in a unit test context is impractical or overly complex. +3. **Mockable**: Not implemented, but can be mocked or patched. For example, `algopy.abi_call` can be mocked to return specific values or behaviours; otherwise, it raises a `NotImplementedError`. This category covers cases where native or emulated implementation in a unit test context is impractical or overly complex. -For a full list of all public `algopy` types and their corresponding implementation category, refer to the [Coverage](coverage.md) section. -``` +For a full list of all public `algopy` types and their corresponding implementation category, refer to the [Coverage](../coverage.md) section. diff --git a/docs/testing-guide/contract-testing.md b/docs/testing-guide/contract-testing.md index 1685b43d..9c28d331 100644 --- a/docs/testing-guide/contract-testing.md +++ b/docs/testing-guide/contract-testing.md @@ -1,6 +1,6 @@ # Smart Contract Testing -This guide provides an overview of how to test smart contracts using the Algorand Python SDK (`algopy`). We will cover the basics of testing `ARC4Contract` and `Contract` classes, focusing on `abimethod` and `baremethod` decorators. +This guide provides an overview of how to test smart contracts using the Algorand Python SDK (`algopy`). It covers the basics of testing `ARC4Contract` and `Contract` classes, focusing on the `abimethod` and `baremethod` decorators. ![](https://mermaid.ink/img/pako:eNqVkrFugzAQhl_Fujnp1ImhEiJrJNREWeoOV9sNVsFG9iEVBd69R5w0JE2llsk2n7-7_-AAymsDGewDtpXYrqQT_GyKFwl5vfcBnRZlT5V3IjYYSCjvKKAiCa-JzXfrObyzgTqsxRpVZZ25YOX2nnRrIomCneZzpszLkllktu0f8ratrUKyjFsXCZ1K2gTH7i01_8dGUjOT_55YeLdUFVr3zRunf5b6R5hZoFnBq9cX72_Br_Cj8bl4vJCHaVucvowYxHk5Xg_sfPkY6SbbphDL5dMgQZu29n0U5DMJwzTVGyApySKZKFSNMXKVxPJYYAGNCQ1azX_VYboqgSrTcAcZLzWGDwnSjcxhR37TOwUZhc4sIPhuX0H2jnXkXddqrrCyyKNpTqfjF5m74B8?type=png) @@ -24,7 +24,7 @@ context = ctx_manager.__enter__() Subclasses of `algopy.ARC4Contract` are **required** to be instantiated with an active test context. As part of instantiation, the test context will automatically create a matching `algopy.Application` object instance. -Within the class implementation, methods decorated with `algopy.arc4.abimethod` and `algopy.arc4.baremethod` will automatically assemble an `algopy.gtxn.ApplicationCallTransaction` transaction to emulate the AVM application call. This behavior can be overriden by setting the transaction group manually as part of test setup, this is done via implicit invocation of `algopy_testing.context.any_application()` _value generator_ (refer to [APIs](../apis.md) for more details). +Within the class implementation, methods decorated with `algopy.arc4.abimethod` and `algopy.arc4.baremethod` will automatically assemble an `algopy.gtxn.ApplicationCallTransaction` to emulate the AVM application call. This behaviour can be overridden by setting the transaction group manually as part of test setup; this is done via implicit invocation of the `algopy_testing.context.any_application()` _value generator_ (refer to the [API](../api.md) for more details). ```{testcode} class SimpleVotingContract(algopy.ARC4Contract): @@ -104,9 +104,9 @@ assert votes == algopy.UInt64(0) For more examples of tests using `algopy.ARC4Contract`, see the [examples](../examples.md) section. -## `algopy.Contract`` +## `algopy.Contract` -Subclasses of `algopy.Contract` are **required** to be instantiated with an active test context. As part of instantiation, the test context will automatically create a matching `algopy.Application` object instance. This behavior is identical to `algopy.ARC4Contract` class instances. +Subclasses of `algopy.Contract` are **required** to be instantiated with an active test context. As part of instantiation, the test context will automatically create a matching `algopy.Application` object instance. This behaviour is identical to `algopy.ARC4Contract` class instances. Unlike `algopy.ARC4Contract`, `algopy.Contract` requires manual setup of the transaction context and explicit method calls. Alternatively, you can use `active_txn_overrides` to specify application arguments and foreign arrays without needing to create a full transaction group if your aim is to patch a specific active transaction related metadata. diff --git a/docs/testing-guide/index.md b/docs/testing-guide/index.md index 2e29c82c..e3ce24d1 100644 --- a/docs/testing-guide/index.md +++ b/docs/testing-guide/index.md @@ -33,7 +33,7 @@ The Algorand Python Testing framework streamlines unit testing of your Algorand 4. Verify logic signatures and subroutines 5. Manage global state, local state, scratch slots, and boxes in test contexts 6. Simulate transactions and transaction groups, including inner transactions -7. Verify opcode behavior +7. Verify opcode behaviour By using this framework, you can ensure your Algorand Python smart contracts function correctly before deploying them to a live network. @@ -44,9 +44,9 @@ Key features of the framework include: - ARC4 Support: Tools for testing ARC4 contracts and methods, including struct definitions and ABI encoding/decoding - Transaction Simulation: Ability to create and execute various transaction types - State Management: Tools for managing and verifying global and local state changes -- Opcode Simulation: Implementations of AVM opcodes for accurate smart contract behavior testing +- Opcode Simulation: Implementations of AVM opcodes for accurate smart contract behaviour testing -The framework is designed to work seamlessly with Algorand Python smart contracts, allowing developers to write comprehensive unit tests that closely mimic the behavior of contracts on the Algorand blockchain. +The framework is designed to work seamlessly with Algorand Python smart contracts, allowing developers to write comprehensive unit tests that closely mimic the behaviour of contracts on the Algorand blockchain. ## Table of Contents diff --git a/docs/testing-guide/opcodes.md b/docs/testing-guide/opcodes.md index 76bf77c4..aa935a6d 100644 --- a/docs/testing-guide/opcodes.md +++ b/docs/testing-guide/opcodes.md @@ -1,6 +1,6 @@ # AVM Opcodes -The [coverage](coverage.md) file provides a comprehensive list of all opcodes and their respective types, categorized as _Mockable_, _Emulated_, or _Native_ within the `algorand-python-testing` package. This section highlights a **subset** of opcodes and types that typically require interaction with the test context manager. +The [coverage](../coverage.md) file provides a comprehensive list of all opcodes and their respective types, categorized as _Mockable_, _Emulated_, or _Native_ within the `algorand-python-testing` package. This section highlights a **subset** of opcodes and types that typically require interaction with the test context manager. `Native` opcodes are assumed to function as they do in the Algorand Virtual Machine, given their stateless nature. If you encounter issues with any `Native` opcodes, please raise an issue in the [`algorand-python-testing` repo](https://github.com/algorandfoundation/algorand-python-testing/issues/new/choose) or contribute a PR following the [Contributing](https://github.com/algorandfoundation/algorand-python-testing/blob/main/CONTRIBUTING.md) guide. @@ -375,7 +375,7 @@ These examples demonstrate how to mock key mockable opcodes in `algorand-python- Mocking these opcodes allows you to: -1. Control complex operations' behavior not covered by _implemented_ and _emulated_ types. +1. Control complex operations' behaviour not covered by _implemented_ and _emulated_ types. 2. Test edge cases and error conditions. 3. Isolate contract logic from external dependencies. diff --git a/docs/testing-guide/transactions.md b/docs/testing-guide/transactions.md index 02ea9516..27805811 100644 --- a/docs/testing-guide/transactions.md +++ b/docs/testing-guide/transactions.md @@ -1,6 +1,6 @@ # Transactions -The testing framework follows the Transaction definitions described in [`algorand-python` docs](https://algorand-python.readthedocs.io/en/latest/algorand_sdk/transactions.html). This section focuses on _value generators_ and interactions with inner transactions, it also explains how the framework identifies _active_ transaction group during contract method/subroutine/logicsig invocation. +The testing framework follows the Transaction definitions described in [`algorand-python` docs](https://algorandfoundation.github.io/puya/lg-transactions.html). This section focuses on _value generators_ and interactions with inner transactions, it also explains how the framework identifies _active_ transaction group during contract method/subroutine/logicsig invocation. ```{testsetup} import algopy @@ -16,7 +16,7 @@ context = ctx_manager.__enter__() ## Group Transactions -Refers to test implementation of transaction stubs available under `algopy.gtxn.*` namespace. Available under [`algopy.TxnValueGenerator`](../api.md) instance accessible via `context.any.txn` property: +Refers to test implementation of transaction stubs available under `algopy.gtxn.*` namespace. Available under [`algopy.TxnValueGenerator`](#_algopy_testing.value_generators.txn.TxnValueGenerator) instance accessible via `context.any.txn` property: ```{mermaid} graph TD @@ -107,7 +107,7 @@ generic_txn = context.any.txn.transaction( When a smart contract instance (application) is interacted with on the Algorand network, it must be performed in relation to a specific transaction or transaction group where one or many transactions are application calls to target smart contract instances. -To emulate this behaviour, the `create_group` context manager is available on [`algopy.TransactionContext`](../api.md) instance that allows setting temporary transaction fields within a specific scope, passing in emulated transaction objects and identifying the active transaction index within the transaction group +To emulate this behaviour, the `create_group` context manager is available on [`algopy.TransactionContext`](#_algopy_testing.context_helpers.txn_context.TransactionContext) instance that allows setting temporary transaction fields within a specific scope, passing in emulated transaction objects and identifying the active transaction index within the transaction group ```{testcode} import algopy @@ -139,7 +139,7 @@ assert len(context.txn.last_group.txns) == 1 Inner transactions are AVM transactions that are signed and executed by AVM applications (instances of deployed smart contracts or signatures). -When testing smart contracts, to stay consistent with AVM, the framework \_does not allow you to submit inner transactions outside of contract/subroutine invocation, but you can interact with and manage inner transactions using the test context manager as follows: +When testing smart contracts, to stay consistent with AVM, the framework _does not allow you to submit inner transactions outside of contract/subroutine invocation_, but you can interact with and manage inner transactions using the test context manager as follows: ```{testcode} class MyContract(algopy.ARC4Contract):