Merge pull request #1558 from onflow/cadence_mobile_docs_edit_cws

Cadence mobile and fork testing doc edits.

Author: briandoyle81

docs/blockchain-development-tutorials/cadence/fork-testing/index.md

@@ -29,32 +29,32 @@ keywords:
   - forked runtime
 ---
 
-# Fork Testing with Cadence
+# Fork testing with Cadence
 
 This tutorial teaches you how to run your Cadence tests against a snapshot of Flow mainnet using `flow test --fork`. You'll learn how to test your contracts against real deployed contracts and production data without needing to deploy anything to a live network or bootstrap test accounts.
 
-Fork testing bridges the gap between isolated local unit tests and testnet deployments. It enables you to validate your contracts work correctly with real on-chain state, test integrations with deployed contracts, and debug issues using historical blockchain data—all in a safe, local environment.
+Fork testing bridges the gap between isolated local unit tests and testnet deployments. It allows you to validate your contracts work correctly with real on-chain state, test integrations with deployed contracts, and debug issues with historical blockchain data—all in a safe, local environment.
 
 ## What You'll Learn
 
-After completing this tutorial, you'll be able to:
+After you complete this tutorial, you'll be able to:
 
-- **Run Cadence tests against forked networks** using `flow test --fork`
-- **Test contracts that depend on real mainnet contracts** without manual setup
-- **Use account impersonation** to execute transactions as any mainnet account
-- **Read from production blockchain state** in your test suite
-- **Pin tests to specific block heights** for historical debugging
-- **Integrate fork testing** into your development workflow
+- **Run Cadence tests against forked networks** with `flow test --fork`.
+- **Test contracts that depend on real mainnet contracts** without manual setup.
+- **Use account impersonation** to execute transactions as any mainnet account.
+- **Read from production blockchain state** in your test suite.
+- **Pin tests to specific block heights** for historical debugging.
+- **Integrate fork testing** into your development workflow.
 
 ## What You'll Build
 
 You'll create a complete fork testing setup that demonstrates:
 
-- Reading from the live FlowToken contract on mainnet
-- Deploying your own contract that interacts with mainnet contracts
-- Testing custom logic against real account balances and state
-- Executing transactions using impersonated mainnet accounts
-- A reusable pattern for integration testing your Flow applications
+- Reading from the live FlowToken contract on mainnet.
+- Deploying your own contract that interacts with mainnet contracts.
+- Testing custom logic against real account balances and state.
+- Executing transactions using impersonated mainnet accounts.
+- A reusable pattern for integration testing your Flow applications.
 
 ### Reproducibility first
 
@@ -64,7 +64,7 @@ Pin a specific block height when you need reproducible results:
 flow test --fork mainnet --fork-height <BLOCK_HEIGHT>
 ```
 
-Document the pin heights you rely on (for example in CI variables or a simple file in the repo) and update them via a dedicated freshness PR. For best results, keep a per‑spork stable pin and also run a "latest" freshness job.
+Document the pin heights you rely on (for example, in CI variables or a simple file in the repo) and update them via a dedicated freshness PR. For best results, keep a per‑spork stable pin and also run a "latest" freshness job.
 
 ## Prerequisites
 
@@ -78,11 +78,11 @@ brew install flow-cli
 
 For other operating systems, refer to the [installation guide].
 
-### Basic Cadence Testing Knowledge
+### Basic Cadence testing knowledge
 
 You should be familiar with writing basic Cadence tests. If you're new to Cadence testing, start with [Testing Smart Contracts] first.
 
-### Network Access
+### Network access
 
 You'll need network access to Flow's public access nodes. The tutorial uses these endpoints, which are freely available:
 
@@ -95,7 +95,7 @@ This tutorial covers `flow test --fork` (running tests against forked network st
 
 :::
 
-## Create Your Project
+## Create your project
 
 Navigate to your development directory and create a new Flow project:
 
@@ -114,7 +114,7 @@ flow init fork-testing-demo --yes
 cd fork-testing-demo
 ```
 
-## Install Dependencies
+## Install dependencies
 
 Use the [Dependency Manager] to install the `FlowToken` and `FungibleToken` contracts:
 
@@ -124,7 +124,7 @@ flow dependencies install FlowToken FungibleToken
 
 This downloads the contracts and their dependencies into the `imports/` folder and updates your `flow.json` with the correct addresses and aliases across all networks (mainnet, testnet, emulator).
 
-Your `flow.json` will now include an entry like:
+Your `flow.json` now includes an entry like:
 
 ```json
 {
@@ -141,7 +141,7 @@ Your `flow.json` will now include an entry like:
 }
 ```
 
-Your `flow.json` should now have the mainnet and testnet networks configured from `flow init`. In fork mode, contract imports automatically resolve to the correct network addresses.
+Your `flow.json` now has the mainnet and testnet networks configured from `flow init`. In fork mode, contract imports automatically resolve to the correct network addresses.
 
 ## Test Reading Live State
 
@@ -185,12 +185,15 @@ access(all) fun testFlowTokenSupplyIsPositive() {
 }
 ```
 
-Notes:
+:::info
+
 - Use `Test.executeScript()` to read contract state
-- The script imports `FlowToken` by name - the dependency manager handles address resolution
-- In fork mode, this automatically uses the mainnet FlowToken contract
-- Extract the return value with proper type casting and assert on it
-- File paths in `Test.readFile()` are relative to the test file location (use `../scripts/` from `cadence/tests/`)
+- The script imports `FlowToken` by name - the dependency manager handles address resolution.
+- In fork mode, this automatically uses the mainnet FlowToken contract.
+- Extract the return value with proper type casting and assert on it.
+- File paths in `Test.readFile()` are relative to the test file location (use `../scripts/` from `cadence/tests/`).
+
+:::
 
 #### Quick verify
 
@@ -206,7 +209,7 @@ Target testnet instead:
 flow test cadence/tests/FlowToken_test.cdc --fork testnet
 ```
 
-You should see the test PASS. If not, verify your network host in `flow.json` and that dependencies are installed.
+You will see the test PASS. If not, verify your network host in `flow.json` and that dependencies are installed.
 
 ## Deploy and Test Your Contract
 
@@ -221,12 +224,13 @@ flow accounts create
 ```
 
 Follow the prompts:
-- Select "mainnet" for the network
-- Name your account as desired
+- Select "mainnet" for the network.
+- Name your account as desired.
 
 This will output the new account address. Use this address as the mainnet alias for your contract in flow.json.
 
 :::note
+
 This creates a local account with a mainnet-format address for fork testing. When you're ready to deploy to actual mainnet, you'll use this same account—see the [Deploying Contracts guide](pathname:///build/cadence/smart-contracts/deploying) for details.
 :::
 
@@ -261,11 +265,11 @@ access(all) contract TokenChecker {
 }
 ```
 
-### Configure Contract in flow.json
+### Configure contract in flow.json
 
 Add the `TokenChecker` contract configuration to `flow.json`. The contract needs a **mainnet alias** so that imports can resolve properly during fork testing.
 
-Update your `flow.json` to include the contract with aliases, using the address you generated in the previous step:
+Update your `flow.json` to include the contract with aliases, and use the address you generated in the previous step:
 
 ```json
 {
@@ -286,9 +290,13 @@ Update your `flow.json` to include the contract with aliases, using the address
 }
 ```
 
-**Note:** No local private key is required for forked tests. The accounts entry above is included so you can copy/reference the address in your config; keys can be omitted for fork tests. Contracts deploy to the testing environment at `testing` alias, and transactions that interact with forked state can use impersonation. The `Test.deployContract` function will automatically deploy your contract to the testing environment during test execution.
+:::info
+
+ No local private key is required for forked tests. The accounts entry above is included so you can copy and reference the address in your config. You can also omit keys for fork tests. Contracts deploy to the testing environment at `testing` alias, and transactions that interact with forked state can use impersonation. The `Test.deployContract` function will automatically deploy your contract to the testing environment during test execution.
+
+ :::
 
-### Create Scripts for Testing
+### Create scripts for testing
 
 Generate the scripts:
 
@@ -317,7 +325,7 @@ access(all) fun main(addr: Address, min: UFix64): Bool {
 }
 ```
 
-### Test Your Contract with Forked State
+### Test Your contract with forked state
 
 Generate the test file:
 
@@ -367,14 +375,14 @@ access(all) fun testHasMinimumBalance() {
 }
 ```
 
-### What's Happening Here
+### What's happening here
 
-1. **Your contract uses FlowToken**: `TokenChecker` imports and interacts with the real FlowToken contract
-2. **No bootstrapping needed**: When you run with `--fork`, real mainnet accounts (like `0x1654653399040a61`, the Flow service account) already have balances
-3. **Test against real state**: You can query actual accounts and verify your contract logic works with production data
-4. **Local deployment**: Your `TokenChecker` contract is deployed locally to the test environment, but it reads from forked mainnet state
+1. **Your contract uses FlowToken**: `TokenChecker` imports and interacts with the real FlowToken contract.
+2. **No bootstrapping needed**: When you run with `--fork`, real mainnet accounts (like `0x1654653399040a61`, the Flow service account) already have balances.
+3. **Test against real state**: You can query actual accounts and verify your contract logic works with production data.
+4. **Local deployment**: Your `TokenChecker` contract is deployed locally to the test environment, but it reads from forked mainnet state.
 
-## Execute Transactions with Account Impersonation
+## Execute transactions with account impersonation
 
 Fork testing includes built-in account impersonation—you can execute transactions as **any mainnet account** without needing private keys. This lets you test interactions with real accounts and their existing state.
 
@@ -433,9 +441,9 @@ transaction(amount: UFix64, to: Address) {
 }
 ```
 
-### Test Transaction Execution with Impersonation
+### Test transaction execution with impersonation
 
-Add this test function to the existing `cadence/tests/TokenChecker_test.cdc` file:
+Add this test function to the current `cadence/tests/TokenChecker_test.cdc` file:
 
 ```cadence
 access(all) fun testTransactionAsMainnetAccount() {
@@ -501,23 +509,23 @@ access(all) fun testTransactionAsMainnetAccount() {
 }
 ```
 
-### Key Points About Account Impersonation
+### Key points about account impersonation
 
-1. **Any account can be used**: Call `Test.getAccount(address)` with any mainnet address
-2. **No private keys needed**: Fork testing has built-in impersonation—you can sign transactions as any account
-3. **Real account state**: The account has its actual mainnet balance, storage, and capabilities
-4. **Mutations are local**: Changes only affect your test environment, not the real network
-5. **Test complex scenarios**: Impersonate whale accounts, protocol accounts, or any user to test edge cases
+1. **Any account can be used**: Call `Test.getAccount(address)` with any mainnet address.
+2. **No private keys needed**: Fork testing has built-in impersonation—you can sign transactions as any account.
+3. **Real account state**: The account has its actual mainnet balance, storage, and capabilities.
+4. **Mutations are local**: Changes only affect your test environment, not the real network.
+5. **Test complex scenarios**: Impersonate whale accounts, protocol accounts, or any user to test edge cases.
 
-## Run All Tests Together
+## Run all tests together
 
 Now that you have multiple test files, run them all against the forked network:
 
 ```zsh
 flow test --fork mainnet
 ```
 
-This runs all `*_test.cdc` files in your project against mainnet. You should see:
+This runs all `*_test.cdc` files in your project against mainnet. You will see:
 
 ```
 Test results: "cadence/tests/FlowToken_test.cdc"
@@ -529,7 +537,7 @@ Test results: "cadence/tests/TokenChecker_test.cdc"
 - PASS: testTransactionAsMainnetAccount
 ```
 
-### Additional Options
+### Additional options
 
 You can also fork from testnet (`flow test --fork testnet`) or pin to a specific block height (`--fork-height`). See the [Fork Testing Flags] reference for all available options.
 
@@ -548,7 +556,7 @@ Fork tests run against Flow chain state only:
 - For end-to-end, combine with `flow emulator --fork` and a local stub service
 :::
 
-### Select Tests Quickly
+### Select tests quickly
 
 - Run specific files or directories:
 
@@ -564,41 +572,41 @@ flow test cadence/tests/TokenChecker_test.cdc --name _smoke --fork mainnet
 
 - Optional: suffix a few functions with `_smoke` for quick PR runs; run the full suite nightly or on protected branches.
 
-## When to Use Fork Testing
+## When to use fork testing
 
 Fork testing is most valuable for:
 
-- Integration testing with real onchain contracts and data
-- Pre-deployment validation before mainnet releases
-- Upgrade testing against production state
-- Reproducing issues at a specific block height
-- Testing interactions with high-value or protocol accounts
-- Validating contract behavior with real-world data patterns
+- Integration testing with real onchain contracts and data.
+- Pre-deployment validation before mainnet releases.
+- Upgrade testing against production state.
+- Reproducing issues at a specific block height.
+- Testing interactions with high-value or protocol accounts.
+- Validating contract behavior with real-world data patterns.
 
 For strategy, limitations, and best practices, see the guide: [Testing Smart Contracts].
 
 ## Conclusion
 
 In this tutorial, you learned how to use fork testing to validate your Cadence contracts against live Flow network state. You created tests that read from real mainnet contracts, deployed custom contracts that interact with production data, and executed transactions using account impersonation—all without deploying to a live network or bootstrapping test accounts.
 
-Now that you have completed this tutorial, you should be able to:
+Now that you have completed this tutorial, you will be able to:
 
-- **Run Cadence tests against forked networks** using `flow test --fork`
-- **Test contracts that depend on real mainnet contracts** without manual setup
-- **Use account impersonation** to execute transactions as any mainnet account
-- **Read from production blockchain state** in your test suite
-- **Pin tests to specific block heights** for historical debugging
-- **Integrate fork testing** into your development workflow
+- **Run Cadence tests against forked networks** with `flow test --fork`.
+- **Test contracts that depend on real mainnet contracts** without manual setup.
+- **Use account impersonation** to execute transactions as any mainnet account.
+- **Read from production blockchain state** in your test suite.
+- **Pin tests to specific block heights** for historical debugging.
+- **Integrate fork testing** into your development workflow.
 
-Fork testing bridges the gap between local unit tests and testnet deployments, enabling you to catch integration issues early and test against real-world conditions. Use it as part of your pre-deployment validation process, alongside emulator unit tests for determinism and isolation, and testnet deployments for final verification.
+Fork testing bridges the gap between local unit tests and testnet deployments, allowing you to catch integration issues early and test against real-world conditions. Use it as part of your pre-deployment validation process, alongside emulator unit tests for determinism and isolation, and testnet deployments for final verification.
 
 ### Next Steps
 
-- Explore additional assertions and helpers in the [Cadence Testing Framework]
-- Add more real-world tests that read from standard contracts like Flow NFT
-- Keep unit tests on the emulator for determinism and isolation; run forked integration tests selectively in CI
-- Review the [Fork Testing Flags] reference for advanced options
-- Learn about [Flow Networks] and public access nodes
+- Explore additional assertions and helpers in the [Cadence Testing Framework].
+- Add more real-world tests that read from standard contracts like Flow NFT.
+- Keep unit tests on the emulator for determinism and isolation; run forked integration tests selectively in CI.
+- Review the [Fork Testing Flags] reference for advanced options.
+- Learn about [Flow Networks] and public access nodes.
 
 <!-- Reference-style links -->