From 5f455520b79d0ae34466c4cbdd6beac3563195b2 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Mon, 6 Nov 2023 11:59:21 -0500 Subject: [PATCH 01/13] prep to move --- docs/cadence/measuring-time.mdx | 2 +- .../smart-contracts/{deploying.mdx => deploying.md} | 2 +- docs/guides/smart-contracts/{overview.mdx => overview.md} | 6 +++--- docs/guides/smart-contracts/{testing.mdx => testing.md} | 0 .../nodes/faq/{developers.mdx => developers.md} | 2 +- .../nodes/faq/{operators.mdx => operators.md} | 8 ++++---- versioned_docs/version-stable/cadence/measuring-time.mdx | 2 +- 7 files changed, 11 insertions(+), 11 deletions(-) rename docs/guides/smart-contracts/{deploying.mdx => deploying.md} (97%) rename docs/guides/smart-contracts/{overview.mdx => overview.md} (93%) rename docs/guides/smart-contracts/{testing.mdx => testing.md} (100%) rename docs/references/run-and-secure/nodes/faq/{developers.mdx => developers.md} (99%) rename docs/references/run-and-secure/nodes/faq/{operators.mdx => operators.md} (97%) diff --git a/docs/cadence/measuring-time.mdx b/docs/cadence/measuring-time.mdx index 26f9366b61..8a8131fae2 100644 --- a/docs/cadence/measuring-time.mdx +++ b/docs/cadence/measuring-time.mdx @@ -26,7 +26,7 @@ and further optimizations are needed to achieve that. As of Feb 2021, the rate of block finalization on Mainnet is more than 0.5 blocks/s; with a standard deviation of ±0.1 blocks/s. Hence, a new block is finalized on average every 2 seconds. Note that block height only has a loose correlation with time, -as [the block rate naturally fluctuates](../references/run-and-secure/nodes/faq/operators.mdx#does-the-blockheight-go-up-1-every-second). +as [the block rate naturally fluctuates](../references/run-and-secure/nodes/faq/operators.md#does-the-blockheight-go-up-1-every-second). In addition to the natural variation described above, there are several theoretical block production attacks that could skew this relationship even further. diff --git a/docs/guides/smart-contracts/deploying.mdx b/docs/guides/smart-contracts/deploying.md similarity index 97% rename from docs/guides/smart-contracts/deploying.mdx rename to docs/guides/smart-contracts/deploying.md index aec8c814cc..188049f05f 100644 --- a/docs/guides/smart-contracts/deploying.mdx +++ b/docs/guides/smart-contracts/deploying.md @@ -25,7 +25,7 @@ Anyone can deploy and update contracts on mainnet. Audits are encouraged but not ### Create and deploy a mainnet project The tool of choice is Flow CLI, there are quickstarts and guides that use Flow CLI, [Getting Started](../../build/getting-started/quickstarts/flow-cli) - It is highly encouraged to test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow any additional guidelines set out here: [Smart Contract Testing Guidelines](./testing). -- Follow the Flow CLI instructions to [Create a Project](../../tools/flow-cli/). You have the Flow CLI installed and ran `flow init` or `flow setup` in your project folder and generating a `flow.json` file +- Follow the Flow CLI instructions to [Create a Project](../../tools/flow-cli/index.md). You have the Flow CLI installed and ran `flow init` or `flow setup` in your project folder and generating a `flow.json` file - Mainnet account: You completed the mainnet account setup, (see above) and have your key pair and mainnet address ready. - [Deploy your project](../../tools/flow-cli/deployment/deploy-project-contracts.md), notice that your account now has contracts deployed on mainnet. - [Deploy a contract](../../tools/flow-cli/accounts/account-add-contract.md) to mainnet. You can deploy contracts individually using the `account-add-contract` command. diff --git a/docs/guides/smart-contracts/overview.mdx b/docs/guides/smart-contracts/overview.md similarity index 93% rename from docs/guides/smart-contracts/overview.mdx rename to docs/guides/smart-contracts/overview.md index a108c81ca9..468bf91655 100644 --- a/docs/guides/smart-contracts/overview.mdx +++ b/docs/guides/smart-contracts/overview.md @@ -23,10 +23,10 @@ To get started with Cadence, we recommended covering the introductory tutorials To build confidently, you will want to set up the appropriate local environment and have an adequate test suite to ensure your smart contracts operate as intended. To do this, familiarize yourself with the following tools: -- [Flow CLI](../../tools/flow-cli/): A utility to directly interact with the chain and manage accounts and contracts. -- [Flow Emulator](../../tools/emulator/): A lightweight server that simulates the Flow blockchain (strongly recommended during development). +- [Flow CLI](../../tools/flow-cli/index.md): A utility to directly interact with the chain and manage accounts and contracts. +- [Flow Emulator](../../tools/emulator/index.md): A lightweight server that simulates the Flow blockchain (strongly recommended during development). - [Flow Dev Wallet](https://github.com/onflow/fcl-dev-wallet/): A utility to simulate user wallets in development. -- [Visual Studio Code Extension](../../tools/vscode-extension/): An IDE integration for developing smart contracts. +- [Visual Studio Code Extension](../../tools/vscode-extension/index.mdx): An IDE integration for developing smart contracts. - [JS Testing Framework](https://github.com/onflow/flow-js-testing): A framework to test your smart contracts. ## Storing Data on Flow diff --git a/docs/guides/smart-contracts/testing.mdx b/docs/guides/smart-contracts/testing.md similarity index 100% rename from docs/guides/smart-contracts/testing.mdx rename to docs/guides/smart-contracts/testing.md diff --git a/docs/references/run-and-secure/nodes/faq/developers.mdx b/docs/references/run-and-secure/nodes/faq/developers.md similarity index 99% rename from docs/references/run-and-secure/nodes/faq/developers.mdx rename to docs/references/run-and-secure/nodes/faq/developers.md index be17a6fde1..8c6622dbf2 100644 --- a/docs/references/run-and-secure/nodes/faq/developers.mdx +++ b/docs/references/run-and-secure/nodes/faq/developers.md @@ -220,7 +220,7 @@ Instructions to generate an address are here: [flow-go-sdk#create-accounts](../. ## Is there a tutorial about how to access flow testnet? From scratch, getting testnet, Flow token etc..? -Yes: [testnet-deployment](../../../../guides/smart-contracts/deploying.mdx) +Yes: [testnet-deployment](../../../../guides/smart-contracts/deploying.md) ## Can you query events between a block range? diff --git a/docs/references/run-and-secure/nodes/faq/operators.mdx b/docs/references/run-and-secure/nodes/faq/operators.md similarity index 97% rename from docs/references/run-and-secure/nodes/faq/operators.mdx rename to docs/references/run-and-secure/nodes/faq/operators.md index f8f22fa0ec..19c9c13277 100644 --- a/docs/references/run-and-secure/nodes/faq/operators.mdx +++ b/docs/references/run-and-secure/nodes/faq/operators.md @@ -113,7 +113,7 @@ You can find out more about events in Cadence here: As an example of the kinds of information events can contain, see the documentation of the events that the staking protocol emits: -[staking/events](../../../../references/run-and-secure/staking/07-staking-scripts-events.md) +[staking/events](../../staking/07-staking-scripts-events.md) ### Consuming Events @@ -160,11 +160,11 @@ No errors should be considered acceptable. If there are errors that are constant ## Is there a testnet/devnet? -There is an access node for you to develop against on the testnet/devnet. You can learn more about it here [testnet-deployment#accessing-flow-testnet](../../../../guides/smart-contracts/deploying.mdx#accessing-flow-testnet) +There is an access node for you to develop against on the testnet/devnet. You can learn more about it here [testnet-deployment#accessing-flow-testnet](../../../../guides/smart-contracts/deploying.md#accessing-flow-testnet) ## Is there a public node? -Yes, an access node is publicly accessible to submit transactions and read data from the blockchain. If you’d like to access the devnet access node to build against, you can do so [here](../../../../references/flow-networks/accessing-testnet.md) +Yes, an access node is publicly accessible to submit transactions and read data from the blockchain. If you’d like to access the devnet access node to build against, you can do so [here](../../../flow-networks/accessing-testnet.md) ## Is it possible to add multiple public keys to a given account/address so that it can be controlled by more than one private key? @@ -192,4 +192,4 @@ You can query the access API to get events for a block range. See Access API spe You can follow Flow node software releases here: [https://github.com/onflow/flow-go/releases](https://github.com/onflow/flow-go/releases). ## How do I run a Flow node and become a node operator? -See the dedicated section on node operation: [nodes/node-operation/](../../../../references/run-and-secure/node-operation/index.md) +See the dedicated section on node operation: [nodes/node-operation/](../../node-operation/index.md) diff --git a/versioned_docs/version-stable/cadence/measuring-time.mdx b/versioned_docs/version-stable/cadence/measuring-time.mdx index 26f9366b61..8a8131fae2 100644 --- a/versioned_docs/version-stable/cadence/measuring-time.mdx +++ b/versioned_docs/version-stable/cadence/measuring-time.mdx @@ -26,7 +26,7 @@ and further optimizations are needed to achieve that. As of Feb 2021, the rate of block finalization on Mainnet is more than 0.5 blocks/s; with a standard deviation of ±0.1 blocks/s. Hence, a new block is finalized on average every 2 seconds. Note that block height only has a loose correlation with time, -as [the block rate naturally fluctuates](../references/run-and-secure/nodes/faq/operators.mdx#does-the-blockheight-go-up-1-every-second). +as [the block rate naturally fluctuates](../references/run-and-secure/nodes/faq/operators.md#does-the-blockheight-go-up-1-every-second). In addition to the natural variation described above, there are several theoretical block production attacks that could skew this relationship even further. From b4f63b5feec8a9579b0b361e846692dc703134f7 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Mon, 6 Nov 2023 12:26:55 -0500 Subject: [PATCH 02/13] move guildes to build --- .../quickstarts/fcl-quickstart.md | 2 +- docs/{ => build}/guides/_category_.json | 0 docs/{ => build}/guides/emulator-output.png | Bin .../{ => build}/guides/flow-app-quickstart.md | 38 +++++++++--------- docs/{ => build}/guides/flow-cli.md | 2 +- docs/{ => build}/guides/flow-dapp-anatomy.png | Bin docs/{ => build}/guides/fungible-token.md | 0 .../guides/hello-world-update-contract.gif | Bin docs/{ => build}/guides/nft.md | 0 .../guides/query-helloWorld-contract.gif | Bin .../guides/smart-contracts/_category_.yml | 0 .../guides/smart-contracts/codecov-in-pr.png | Bin .../smart-contracts/codecov-insights.png | Bin .../guides/smart-contracts/deploying.md | 30 +++++++------- .../smart-contracts/hybrid-custody-ci.png | Bin .../guides/smart-contracts/overview.md | 16 ++++---- .../guides/smart-contracts/testing.md | 8 ++-- .../guides/user-login-hello-world.gif | Bin .../run-and-secure/nodes/faq/developers.md | 2 +- .../run-and-secure/nodes/faq/operators.md | 2 +- docs/tools/clients/fcl-js/api.md | 2 +- docs/tools/clients/fcl-js/authentication.md | 2 +- docs/tools/clients/fcl-js/index.md | 2 +- docusaurus.config.js | 6 --- 24 files changed, 53 insertions(+), 59 deletions(-) rename docs/{ => build}/guides/_category_.json (100%) rename docs/{ => build}/guides/emulator-output.png (100%) rename docs/{ => build}/guides/flow-app-quickstart.md (87%) rename docs/{ => build}/guides/flow-cli.md (98%) rename docs/{ => build}/guides/flow-dapp-anatomy.png (100%) rename docs/{ => build}/guides/fungible-token.md (100%) rename docs/{ => build}/guides/hello-world-update-contract.gif (100%) rename docs/{ => build}/guides/nft.md (100%) rename docs/{ => build}/guides/query-helloWorld-contract.gif (100%) rename docs/{ => build}/guides/smart-contracts/_category_.yml (100%) rename docs/{ => build}/guides/smart-contracts/codecov-in-pr.png (100%) rename docs/{ => build}/guides/smart-contracts/codecov-insights.png (100%) rename docs/{ => build}/guides/smart-contracts/deploying.md (74%) rename docs/{ => build}/guides/smart-contracts/hybrid-custody-ci.png (100%) rename docs/{ => build}/guides/smart-contracts/overview.md (84%) rename docs/{ => build}/guides/smart-contracts/testing.md (88%) rename docs/{ => build}/guides/user-login-hello-world.gif (100%) diff --git a/docs/build/getting-started/quickstarts/fcl-quickstart.md b/docs/build/getting-started/quickstarts/fcl-quickstart.md index ded4343bda..0a8643c767 100644 --- a/docs/build/getting-started/quickstarts/fcl-quickstart.md +++ b/docs/build/getting-started/quickstarts/fcl-quickstart.md @@ -138,4 +138,4 @@ You just built an app on Flow! ## Mutating Chain State and More -For a deeper dive into writing an FCL app, such as how to change the chain state with FCL, check out [this guide](../../../guides/flow-app-quickstart.md) or the [FCL documentation](../../../tools/clients/fcl-js/index.md). \ No newline at end of file +For a deeper dive into writing an FCL app, such as how to change the chain state with FCL, check out [this guide](../../guides/flow-app-quickstart.md) or the [FCL documentation](../../../tools/clients/fcl-js/index.md). \ No newline at end of file diff --git a/docs/guides/_category_.json b/docs/build/guides/_category_.json similarity index 100% rename from docs/guides/_category_.json rename to docs/build/guides/_category_.json diff --git a/docs/guides/emulator-output.png b/docs/build/guides/emulator-output.png similarity index 100% rename from docs/guides/emulator-output.png rename to docs/build/guides/emulator-output.png diff --git a/docs/guides/flow-app-quickstart.md b/docs/build/guides/flow-app-quickstart.md similarity index 87% rename from docs/guides/flow-app-quickstart.md rename to docs/build/guides/flow-app-quickstart.md index fbce55afc7..0a1c4e29c8 100644 --- a/docs/guides/flow-app-quickstart.md +++ b/docs/build/guides/flow-app-quickstart.md @@ -14,7 +14,7 @@ sidebar_custom_props: This guide is a simple walkthrough to get started building a web3 app using the Flow Client Library (FCL). - If you are looking for a scalfolds, check out [scaffolds available in the Flow CLI](../tools/flow-cli/super-commands.md#using-scaffolds). +If you are looking for a scalfolds, check out [scaffolds available in the Flow CLI](../../tools/flow-cli/super-commands.md#using-scaffolds). This simple guide uses the "Hello World" scaffold, it is meant to provide all the code needed to get a web application up and running. @@ -24,10 +24,10 @@ This simple guide uses the "Hello World" scaffold, it is meant to provide all th ![Flow app anatomy](flow-dapp-anatomy.png) -FCL (aka Flow Client Library) wraps the logic needed to communicate with the Flow blockchain. It's a npm package, [More Information](../tools/clients/fcl-js) +FCL (aka Flow Client Library) wraps the logic needed to communicate with the Flow blockchain. It's a npm package, [More Information](../../tools/clients/fcl-js) -This guide assumes a good understanding of React. The concepts are easy to understand and apply to other libraries and framework. A strong understanding of Cadence (Flow's smart contract language) is not required. More information on Cadence, [learning the Cadence language](../build/cadence.md). +This guide assumes a good understanding of React. The concepts are easy to understand and apply to other libraries and framework. A strong understanding of Cadence (Flow's smart contract language) is not required. More information on Cadence, [learning the Cadence language](../cadence.md). ### FCL concepts covered: @@ -42,7 +42,7 @@ For more help, [Discord](https://discord.gg/flow). See links at the end of this ## Installation -Make sure you have Flow CLI installed. [installation instructions](../tools/flow-cli/install.md). +Make sure you have Flow CLI installed. [installation instructions](../../tools/flow-cli/install.md). ## Configuration @@ -58,7 +58,7 @@ npm install # run the app in a later step ``` -We don't recommend keeping private keys in your `flow.json`, notice that Flow CLI already moved the emulator private key to a `emulator.key` file and point to it using the [key/location pattern](../tools/flow-cli/flow.json/security.md#private-account-configuration-file). This file should be added to your `.gitignore` file, so it won't be committed to your repository. +We don't recommend keeping private keys in your `flow.json`, notice that Flow CLI already moved the emulator private key to a `emulator.key` file and point to it using the [key/location pattern](../../tools/flow-cli/flow.json/security.md#private-account-configuration-file). This file should be added to your `.gitignore` file, so it won't be committed to your repository. We won't be using emulator and running contracts locally in this quickstart, but FCL will complain if it finds private keys in your `flow.json` file. @@ -85,7 +85,7 @@ Your `flow.json` file should look like this: ``` -The `flow.json` file is used to keep track of deployed contracts and accounts. [More Information](../tools/clients/fcl-js/api#using-flowjson) +The `flow.json` file is used to keep track of deployed contracts and accounts. [More Information](../../tools/clients/fcl-js/api#using-flowjson) @@ -104,7 +104,7 @@ The `hello-world` web application comes with convenience npm commands to facilit 3. Start web app -Emulator is a local blockchain [More Information](../tools/emulator/index.md). Emulator has all the features as testnet and mainnet blockchains +Emulator is a local blockchain [More Information](../../tools/emulator/index.md). Emulator has all the features as testnet and mainnet blockchains ```sh @@ -113,12 +113,12 @@ npm run dev:local Now that your app is running. FCL loads the configuration in `config/fcl.ts` This file contains configuration information for FCL, such as what Access Node and wallet discovery endpoint and which network to use (e.g. testnet or a local emulator). -- `accessNode.api` key specifies the address of a Flow access node. There are publically available access nodes, but have to rate limit. Alternatively, applications might want to run an Observer node [Run a Node](../references/run-and-secure/node-operation/observer-node.mdx). +- `accessNode.api` key specifies the address of a Flow access node. There are publically available access nodes, but have to rate limit. Alternatively, applications might want to run an Observer node [Run a Node](../../references/run-and-secure/node-operation/observer-node.mdx). - `discovery.wallet` is an address that points to a service that lists FCL compatible wallets. Flow's FCL Discovery service is a service that FCL wallet providers can be added to, and be made 'discoverable' to any application that uses the `discovery.wallet` endpoint. Also, notice that `package.json` uses `NEXT_PUBLIC_FLOW_NETWORK=local` for `dev` command, this is used to set the network in `config/fcl.ts`. -Learn more about [configuring Discovery](../tools/clients/fcl-js/discovery.mdx) or [setting configuration values](../tools/clients/fcl-js/api.md#setting-configuration-values). +Learn more about [configuring Discovery](../../tools/clients/fcl-js/discovery.mdx) or [setting configuration values](../../tools/clients/fcl-js/api.md#setting-configuration-values). The main Next.js app component is located in `pages/_app.tsx`. It should import the config file `config/fcl.ts` already and should look like this: @@ -194,11 +194,11 @@ The web app will run, but there are no contracts deployed to local emulator. Thi Note: in the code above `useCurrentUser` is used to determine if there is a logged in user. -There are two methods to allow the user to login. `fcl.logIn()` or `fcl.authenticate()` [More Information on, authenticate](../tools/clients/fcl-js/api#authenticate) +There are two methods to allow the user to login. `fcl.logIn()` or `fcl.authenticate()` [More Information on, authenticate](../../tools/clients/fcl-js/api#authenticate) In `components/Navbar.tsx` a button wires up the authentication method `fcl.authenticate()`. It is used to bring up the list of supported wallets. See below -Once authenticated, FCL uses a hook `const user = useCurrentUser()` to get the user data, when user is signed in `user.loggedIn` flag is `true`. For more information on the `currentUser`, read more [here](../tools/clients/fcl-js/api.md#current-user). +Once authenticated, FCL uses a hook `const user = useCurrentUser()` to get the user data, when user is signed in `user.loggedIn` flag is `true`. For more information on the `currentUser`, read more [here](../../tools/clients/fcl-js/api.md#current-user). ```jsx import Head from 'next/head' @@ -304,7 +304,7 @@ Verify that `flow.json` updates with HelloWorld contract information, `contracts } ``` -For more information on deployments check [Flow CLI](../tools/flow-cli/flow.json/manage-configuration.md) documentation +For more information on deployments check [Flow CLI](../../tools/flow-cli/flow.json/manage-configuration.md) documentation ## Query the Blockchain @@ -371,7 +371,7 @@ In `components/Container.tsx` file, the `mutateGreeting` method `fcl.mutate` sen That's it! You now have Flow app that uses auth, query and mutate the chain. This is just the beginning. There is so much more to know. Next steps: **Cadence** -- [Cadence Playground Tutorials](../cadence/tutorial/01-first-steps.md) +- [Cadence Playground Tutorials](../../cadence/tutorial/01-first-steps.md) - [Cadence Hello World Video](https://www.youtube.com/watch?v=pRz7EzrWchs) - [Why Cadence?](https://www.onflow.org/post/flow-blockchain-cadence-programming-language-resources-assets) @@ -383,11 +383,11 @@ That's it! You now have Flow app that uses auth, query and mutate the chain. Thi - [Beginner Example: CryptoDappy](https://github.com/bebner/crypto-dappy) **More FCL** -- [FCL API Quick Reference](../tools/clients/fcl-js/api) -- [More on Scripts](../tools/clients/fcl-js/scripts.mdx) -- [More on Transactions](../tools/clients/fcl-js/transactions.mdx) -- [User Signatures](../tools/clients/fcl-js/user-signatures.mdx) -- [Proving Account Ownership](../tools/clients/fcl-js/proving-authentication.mdx) +- [FCL API Quick Reference](../../tools/clients/fcl-js/api) +- [More on Scripts](../../tools/clients/fcl-js/scripts.mdx) +- [More on Transactions](../../tools/clients/fcl-js/transactions.mdx) +- [User Signatures](../../tools/clients/fcl-js/user-signatures.mdx) +- [Proving Account Ownership](../../tools/clients/fcl-js/proving-authentication.mdx) **Other** -- [Flow Developer Onboarding Guide](/tutorials/intro.md) +- [Flow Developer Onboarding Guide](../../tutorials/intro.md) diff --git a/docs/guides/flow-cli.md b/docs/build/guides/flow-cli.md similarity index 98% rename from docs/guides/flow-cli.md rename to docs/build/guides/flow-cli.md index 677bb62fb3..d63623b0e5 100644 --- a/docs/guides/flow-cli.md +++ b/docs/build/guides/flow-cli.md @@ -109,4 +109,4 @@ And then the flow dev: ### Next steps -As part of the next steps you can read more about [flow dev command](../tools/flow-cli/super-commands.md). +As part of the next steps you can read more about [flow dev command](../../tools/flow-cli/super-commands.md). diff --git a/docs/guides/flow-dapp-anatomy.png b/docs/build/guides/flow-dapp-anatomy.png similarity index 100% rename from docs/guides/flow-dapp-anatomy.png rename to docs/build/guides/flow-dapp-anatomy.png diff --git a/docs/guides/fungible-token.md b/docs/build/guides/fungible-token.md similarity index 100% rename from docs/guides/fungible-token.md rename to docs/build/guides/fungible-token.md diff --git a/docs/guides/hello-world-update-contract.gif b/docs/build/guides/hello-world-update-contract.gif similarity index 100% rename from docs/guides/hello-world-update-contract.gif rename to docs/build/guides/hello-world-update-contract.gif diff --git a/docs/guides/nft.md b/docs/build/guides/nft.md similarity index 100% rename from docs/guides/nft.md rename to docs/build/guides/nft.md diff --git a/docs/guides/query-helloWorld-contract.gif b/docs/build/guides/query-helloWorld-contract.gif similarity index 100% rename from docs/guides/query-helloWorld-contract.gif rename to docs/build/guides/query-helloWorld-contract.gif diff --git a/docs/guides/smart-contracts/_category_.yml b/docs/build/guides/smart-contracts/_category_.yml similarity index 100% rename from docs/guides/smart-contracts/_category_.yml rename to docs/build/guides/smart-contracts/_category_.yml diff --git a/docs/guides/smart-contracts/codecov-in-pr.png b/docs/build/guides/smart-contracts/codecov-in-pr.png similarity index 100% rename from docs/guides/smart-contracts/codecov-in-pr.png rename to docs/build/guides/smart-contracts/codecov-in-pr.png diff --git a/docs/guides/smart-contracts/codecov-insights.png b/docs/build/guides/smart-contracts/codecov-insights.png similarity index 100% rename from docs/guides/smart-contracts/codecov-insights.png rename to docs/build/guides/smart-contracts/codecov-insights.png diff --git a/docs/guides/smart-contracts/deploying.md b/docs/build/guides/smart-contracts/deploying.md similarity index 74% rename from docs/guides/smart-contracts/deploying.md rename to docs/build/guides/smart-contracts/deploying.md index 188049f05f..0e220010ce 100644 --- a/docs/guides/smart-contracts/deploying.md +++ b/docs/build/guides/smart-contracts/deploying.md @@ -16,19 +16,19 @@ Make sure you handle your mainnet account keys appropriately. Using a Key Manage ### Creating an Account There are two simple methods of creating an account on testnet. **Interactive** and **Manual**, both use the Flow CLI. On mainnet you will have to fund your newly created account, there is no faucet. -Make sure to install the Flow CLI. [Flow CLI](../../tools/flow-cli/accounts/create-accounts) has a interactive mode for generating keys. +Make sure to install the Flow CLI. [Flow CLI](../../../tools/flow-cli/accounts/create-accounts) has a interactive mode for generating keys. Anyone can deploy and update contracts on mainnet. Audits are encouraged but not mandatory to deploying contracts to mainnet. Take every precauction to reduce issues and protect users. ### Create and deploy a mainnet project -The tool of choice is Flow CLI, there are quickstarts and guides that use Flow CLI, [Getting Started](../../build/getting-started/quickstarts/flow-cli) +The tool of choice is Flow CLI, there are quickstarts and guides that use Flow CLI, [Getting Started](../../getting-started/quickstarts/flow-cli) - It is highly encouraged to test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow any additional guidelines set out here: [Smart Contract Testing Guidelines](./testing). -- Follow the Flow CLI instructions to [Create a Project](../../tools/flow-cli/index.md). You have the Flow CLI installed and ran `flow init` or `flow setup` in your project folder and generating a `flow.json` file +- Follow the Flow CLI instructions to [Create a Project](../../../tools/flow-cli/index.md). You have the Flow CLI installed and ran `flow init` or `flow setup` in your project folder and generating a `flow.json` file - Mainnet account: You completed the mainnet account setup, (see above) and have your key pair and mainnet address ready. -- [Deploy your project](../../tools/flow-cli/deployment/deploy-project-contracts.md), notice that your account now has contracts deployed on mainnet. -- [Deploy a contract](../../tools/flow-cli/accounts/account-add-contract.md) to mainnet. You can deploy contracts individually using the `account-add-contract` command. +- [Deploy your project](../../../tools/flow-cli/deployment/deploy-project-contracts.md), notice that your account now has contracts deployed on mainnet. +- [Deploy a contract](../../../tools/flow-cli/accounts/account-add-contract.md) to mainnet. You can deploy contracts individually using the `account-add-contract` command. All your contract deployment addresses are stored in `flow.json`. Mainnet, Testnet and local (emulator) are stored as well. @@ -36,19 +36,19 @@ All your contract deployment addresses are stored in `flow.json`. Mainnet, Testn ### Deploy updated contracts on mainnet -Contracts can be updated and retain the contract address. You can use the [Flow CLI contract update command](../../tools/flow-cli/accounts/account-update-contract.md) to re-deploy an updated version of your contract: +Contracts can be updated and retain the contract address. You can use the [Flow CLI contract update command](../../../tools/flow-cli/accounts/account-update-contract.md) to re-deploy an updated version of your contract: If you see `Error Code: 1103`, your new account does not have enough funds to complete the transaction. Make sure you have enough FLOW and your account is set up correctly, check [Flowdiver](https://flowdiver.io/) to verify. -Once all your contracts are deployed, you can visit [flow-view-source](https://flow-view-source.com/) or run the [Flow CLI get account command](../../tools/flow-cli/accounts/get-accounts.md) to confirm the deployment. +Once all your contracts are deployed, you can visit [flow-view-source](https://flow-view-source.com/) or run the [Flow CLI get account command](../../../tools/flow-cli/accounts/get-accounts.md) to confirm the deployment. ### Sporks -Currently, **historical event data is not migrated between sporks,** so you'll need to design your application with this in mind. We recognize the usefulness of historical event data and plan on adding a means of accessing it in the near future. Past spork transactional data is available, [See Previous Spork Access Node Info](../../references/run-and-secure/node-operation/past-sporks) +Currently, **historical event data is not migrated between sporks,** so you'll need to design your application with this in mind. We recognize the usefulness of historical event data and plan on adding a means of accessing it in the near future. Past spork transactional data is available, [See Previous Spork Access Node Info](../../../references/run-and-secure/node-operation/past-sporks) -More Information on [Sporks](../../references/run-and-secure/node-operation/spork) +More Information on [Sporks](../../../references/run-and-secure/node-operation/spork) ### Testnet @@ -56,13 +56,13 @@ More Information on [Sporks](../../references/run-and-secure/node-operation/spor The Flow test network, known as Flow Testnet, exists to help developers test their software and smart contracts against a live network. It's also used as a means of releasing and testing new protocol and smart contract features before they are integrated into Flow's main network (Mainnet). -When the Flow protocol is updated or a new version of Cadence is released, those updates will always be made available on the [Flow Emulator](../../tools/emulator) _before_ they're integrated into Flow Testnet or Flow Mainnet. +When the Flow protocol is updated or a new version of Cadence is released, those updates will always be made available on the [Flow Emulator](../../../tools/emulator) _before_ they're integrated into Flow Testnet or Flow Mainnet. ## Getting Started on Testnet If you need to create a flow.json file to store information about accounts and contracts use the `flow init` command to create a project -To create accounts and generate keys, make sure to install [Flow CLI](../../tools/flow-cli/install). Flow CLI provides convenient functions to simplifies interacting with the blockchain. +To create accounts and generate keys, make sure to install [Flow CLI](../../../tools/flow-cli/install). Flow CLI provides convenient functions to simplifies interacting with the blockchain. @@ -70,22 +70,22 @@ To create accounts and generate keys, make sure to install [Flow CLI](../../tool There is a simple Flow CLI command to run to create an account. `flow accounts create` command will create a new account and generate a key pair then add the account to your flow.json. The command will try and You can also use the [Testnet Faucet](https://testnet-faucet-v2.onflow.org/) to create and fund an account. -More information about [Flow CLI](../../tools/flow-cli/accounts/create-accounts) and creating accounts. +More information about [Flow CLI](../../../tools/flow-cli/accounts/create-accounts) and creating accounts. ### Creating and deploying a Project -Flow CLI can be used to create a Cadence project and stay organized, [Flow CLI: Create a project](../../tools/flow-cli). This will make deployment much easiler and help with the iterative development process. +Flow CLI can be used to create a Cadence project and stay organized, [Flow CLI: Create a project](../../../tools/flow-cli). This will make deployment much easiler and help with the iterative development process. After you have a project created and want to deploy your Cadence; contracts, transactions and scripts. `flow accounts add-contract --signer --network testnet` will deploy your contract to testnet. -More information on how to use Flow CLI to [deploy](../../tools/flow-cli/deployment/deploy-project-contracts.md). +More information on how to use Flow CLI to [deploy](../../../tools/flow-cli/deployment/deploy-project-contracts.md). Make sure Flow project was initialized in the previous step and the `flow.json` is present. ### Making Use of Core Contracts -Flow Testnet comes with some useful contracts already deployed, called **core contracts.** More information and import addresses for the [core contracts](../../references/core-contracts/index.md). +Flow Testnet comes with some useful contracts already deployed, called **core contracts.** More information and import addresses for the [core contracts](../../../references/core-contracts/index.md). Once your accounts are set up and you're ready to develop, you can look over [some code examples from the Flow Go SDK](https://github.com/onflow/flow-go-sdk/tree/master/examples). diff --git a/docs/guides/smart-contracts/hybrid-custody-ci.png b/docs/build/guides/smart-contracts/hybrid-custody-ci.png similarity index 100% rename from docs/guides/smart-contracts/hybrid-custody-ci.png rename to docs/build/guides/smart-contracts/hybrid-custody-ci.png diff --git a/docs/guides/smart-contracts/overview.md b/docs/build/guides/smart-contracts/overview.md similarity index 84% rename from docs/guides/smart-contracts/overview.md rename to docs/build/guides/smart-contracts/overview.md index 468bf91655..4839876738 100644 --- a/docs/guides/smart-contracts/overview.md +++ b/docs/build/guides/smart-contracts/overview.md @@ -23,10 +23,10 @@ To get started with Cadence, we recommended covering the introductory tutorials To build confidently, you will want to set up the appropriate local environment and have an adequate test suite to ensure your smart contracts operate as intended. To do this, familiarize yourself with the following tools: -- [Flow CLI](../../tools/flow-cli/index.md): A utility to directly interact with the chain and manage accounts and contracts. -- [Flow Emulator](../../tools/emulator/index.md): A lightweight server that simulates the Flow blockchain (strongly recommended during development). +- [Flow CLI](../../../tools/flow-cli/index.md): A utility to directly interact with the chain and manage accounts and contracts. +- [Flow Emulator](../../../tools/emulator/index.md): A lightweight server that simulates the Flow blockchain (strongly recommended during development). - [Flow Dev Wallet](https://github.com/onflow/fcl-dev-wallet/): A utility to simulate user wallets in development. -- [Visual Studio Code Extension](../../tools/vscode-extension/index.mdx): An IDE integration for developing smart contracts. +- [Visual Studio Code Extension](../../../tools/vscode-extension/index.mdx): An IDE integration for developing smart contracts. - [JS Testing Framework](https://github.com/onflow/flow-js-testing): A framework to test your smart contracts. ## Storing Data on Flow @@ -39,7 +39,7 @@ Permanence is a key property of blockchains; users trust that the data they stor ### Storage Limits & Fees -However, there are practical constraints to storing data on a blockchain. Developer and user accounts must retain a small amount of FLOW tokens, known as the storage fee, for bytes of data stored in their accounts. The minimum storage fee will grant each account a minimum storage amount. If an account holds assets that demand more bytes of storage, the account will need to retain more FLOW tokens to increase the storage amount according to Flow's [fee schedule](../../build/basics/fees.md#fees). A more compact data model can keep storage needs down. \ +However, there are practical constraints to storing data on a blockchain. Developer and user accounts must retain a small amount of FLOW tokens, known as the storage fee, for bytes of data stored in their accounts. The minimum storage fee will grant each account a minimum storage amount. If an account holds assets that demand more bytes of storage, the account will need to retain more FLOW tokens to increase the storage amount according to Flow's [fee schedule](../../basics/fees.md#fees). A more compact data model can keep storage needs down. \ \ Furthermore, a single Flow transaction has a size limit of 4MB, which limits the rate at which large amounts of data can be transferred to the blockchain. @@ -61,9 +61,9 @@ The Flow blockchain has existing smart contract standards for both fungible and ### Non-Fungible Tokens (NFTs) -All NFTs on the Flow blockchain implement the [NonFungibleToken](../../references/core-contracts/08-non-fungible-token.md) interface, allowing them to be compatible with wallets, marketplaces and other cross-app experiences. +All NFTs on the Flow blockchain implement the [NonFungibleToken](../../../references/core-contracts/08-non-fungible-token.md) interface, allowing them to be compatible with wallets, marketplaces and other cross-app experiences. -- [Non-Fungible Token (NFT) contract interface](../../references/core-contracts/08-non-fungible-token.md) +- [Non-Fungible Token (NFT) contract interface](../../../references/core-contracts/08-non-fungible-token.md) ### NFT Sales and Trading @@ -73,6 +73,6 @@ Flow has a standard contract to facilitate both the direct sales and peer-to-pee ### Fungible Tokens -Fungible tokens (i.e. coins, currencies) on the Flow blockchain, including the default cryptocurrency token FLOW, implement the [FungibleToken](../../references/core-contracts/02-fungible-token.md) interface. +Fungible tokens (i.e. coins, currencies) on the Flow blockchain, including the default cryptocurrency token FLOW, implement the [FungibleToken](../../../references/core-contracts/02-fungible-token.md) interface. -- [Fungible Token contract interface](../../references/core-contracts/02-fungible-token.md) +- [Fungible Token contract interface](../../../references/core-contracts/02-fungible-token.md) diff --git a/docs/guides/smart-contracts/testing.md b/docs/build/guides/smart-contracts/testing.md similarity index 88% rename from docs/guides/smart-contracts/testing.md rename to docs/build/guides/smart-contracts/testing.md index e812491841..c897846f8e 100644 --- a/docs/guides/smart-contracts/testing.md +++ b/docs/build/guides/smart-contracts/testing.md @@ -11,7 +11,7 @@ Testing is an essential part of the development workflow and code coverage is an Good test coverage is vital for assuring code quality. -Leverage [Flow emulator](../../tools/emulator/index.md) to automate test runs. Test on Flow testnet. Include unit tests; to exercise each feature, and integration tests; to exercise the behavior of different parts of the project as a whole. +Leverage [Flow emulator](../../../tools/emulator/index.md) to automate test runs. Test on Flow testnet. Include unit tests; to exercise each feature, and integration tests; to exercise the behavior of different parts of the project as a whole. The emulator can also provide [code coverage](https://github.com/m-Peter/flow-code-coverage#for-emulator) insights. @@ -39,10 +39,10 @@ In all three cases, the test code will need to deploy the contracts, configure a ### Cadence tests Cadence comes with built-in support for code coverage, as well as a native testing framework which allows developers to write their tests using Cadence. -This framework is bundled with the [Flow CLI](../../tools/flow-cli/index.md) tool, which includes a dedicated command for running tests (`flow test`). +This framework is bundled with the [Flow CLI](../../../tools/flow-cli/index.md) tool, which includes a dedicated command for running tests (`flow test`). You can find examples of Cadence tests in the following projects: [hybrid-custody](https://github.com/onflow/hybrid-custody/tree/main/test), [flow-nft](https://github.com/onflow/flow-nft/tree/master/tests), [flow-ft](https://github.com/onflow/flow-ft/tree/master/tests). -Visit the [documentation](../../cadence/testing-framework.mdx) to view all the available features. +Visit the [documentation](../../../cadence/testing-framework.mdx) to view all the available features. The [Hybrid Custody](https://github.com/onflow/hybrid-custody#readme) project is a prime example which utilizes both the Cadence testing framework and code coverage in its CI. @@ -87,5 +87,5 @@ Tests should also be runnable in automated environments (CI). You can use the [J Once you deployed your application to the testnet, you should record how your application handles non-trivial amounts of traffic to ensure there are no issues. -Get familiar with the [Cadence anti-patterns](../../cadence/anti-patterns.md) to avoid avoid problematic or unintended behavior. +Get familiar with the [Cadence anti-patterns](../../../cadence/anti-patterns.md) to avoid avoid problematic or unintended behavior. \ No newline at end of file diff --git a/docs/guides/user-login-hello-world.gif b/docs/build/guides/user-login-hello-world.gif similarity index 100% rename from docs/guides/user-login-hello-world.gif rename to docs/build/guides/user-login-hello-world.gif diff --git a/docs/references/run-and-secure/nodes/faq/developers.md b/docs/references/run-and-secure/nodes/faq/developers.md index 8c6622dbf2..8b3e6ca9cf 100644 --- a/docs/references/run-and-secure/nodes/faq/developers.md +++ b/docs/references/run-and-secure/nodes/faq/developers.md @@ -220,7 +220,7 @@ Instructions to generate an address are here: [flow-go-sdk#create-accounts](../. ## Is there a tutorial about how to access flow testnet? From scratch, getting testnet, Flow token etc..? -Yes: [testnet-deployment](../../../../guides/smart-contracts/deploying.md) +Yes: [testnet-deployment](../../../../build/guides/smart-contracts/deploying.md) ## Can you query events between a block range? diff --git a/docs/references/run-and-secure/nodes/faq/operators.md b/docs/references/run-and-secure/nodes/faq/operators.md index 19c9c13277..b32483572d 100644 --- a/docs/references/run-and-secure/nodes/faq/operators.md +++ b/docs/references/run-and-secure/nodes/faq/operators.md @@ -160,7 +160,7 @@ No errors should be considered acceptable. If there are errors that are constant ## Is there a testnet/devnet? -There is an access node for you to develop against on the testnet/devnet. You can learn more about it here [testnet-deployment#accessing-flow-testnet](../../../../guides/smart-contracts/deploying.md#accessing-flow-testnet) +There is an access node for you to develop against on the testnet/devnet. You can learn more about it here [testnet-deployment#accessing-flow-testnet](../../../../build/guides/smart-contracts/deploying.md#accessing-flow-testnet) ## Is there a public node? diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index b30477fd36..a3a65530f5 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -647,7 +647,7 @@ export const signMessage = async () => { Discovery abstracts away code so that developers don't have to deal with the discovery of Flow compatible wallets, integration, or authentication. Using `discovery` from FCL allows dapps to list and authenticate with wallets while having full control over the UI. Common use cases for this are login or registration pages. -(Alternatively, if you don't need control over your UI you can continue to use the `discovery.wallet` config value documented in the [Quickstart](../../../guides/flow-app-quickstart.md) for the simplest configuration.) +(Alternatively, if you don't need control over your UI you can continue to use the `discovery.wallet` config value documented in the [Quickstart](../../../build/guides/flow-app-quickstart.md) for the simplest configuration.) > ⚠️**The following methods can only be used in web browsers.** diff --git a/docs/tools/clients/fcl-js/authentication.md b/docs/tools/clients/fcl-js/authentication.md index d033fbb925..6865b5f2fb 100644 --- a/docs/tools/clients/fcl-js/authentication.md +++ b/docs/tools/clients/fcl-js/authentication.md @@ -42,6 +42,6 @@ The TL;DR is to call `fcl.authenticate()` and `fcl.unauthenticate()` respectivel On Flow mainnet, you wont even need to configure anything for this to work, the users of your dapp will go through the authentication process and be able to use any FCL compatible wallet providers. During development you will probably want to configure your dapp to use [`@onflow/dev-wallet`](https://github.com/onflow/fcl-dev-wallet). -The [Quick Start](../../../guides/flow-app-quickstart.md) guide will walk you through using it. +The [Quick Start](../../../build/guides/flow-app-quickstart.md) guide will walk you through using it. We know this can all be fairly overwhelming, we are commited to help though. If you run into any problems, reach out to us on [Discord](https://discord.gg/k6cZ7QC), we are more than happy to help out. diff --git a/docs/tools/clients/fcl-js/index.md b/docs/tools/clients/fcl-js/index.md index faf5e0f771..e706a2608e 100644 --- a/docs/tools/clients/fcl-js/index.md +++ b/docs/tools/clients/fcl-js/index.md @@ -114,7 +114,7 @@ const txId = await fcl.mutate({ ## Next Steps -See the [Flow App Quick Start](../../../guides/flow-app-quickstart.md). +See the [Flow App Quick Start](../../../build/guides/flow-app-quickstart.md). See the full [API Reference](./api.md) for all FCL functionality. diff --git a/docusaurus.config.js b/docusaurus.config.js index 62beae2b2e..d2d92c426f 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -266,12 +266,6 @@ const config = { label: 'Build', activeBasePath: '/build', }, - { - to: 'guides/flow-app-quickstart', - position: 'left', - label: 'Guides', - activeBasePath: '/guides', - }, { to: 'cadence/intro', position: 'left', From 1e5fb5f683e34b015345ef0a32efcba391ebbef9 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Mon, 6 Nov 2023 13:47:44 -0500 Subject: [PATCH 03/13] move testing --- docs/build/building-vs-other-chains.md | 2 +- docs/build/getting-started/explore-more.mdx | 6 +++--- docs/build/guides/smart-contracts/deploying.md | 2 +- .../smart-contracts/testing/intro.md} | 12 ++++++------ .../smart-contracts/testing/testing-framework.md} | 8 ++++---- .../smart-contracts/{ => testing}/testing.md | 14 +++++++------- docs/tools/flow-cli/tests/run-tests.md | 2 +- docusaurus.config.js | 2 +- src/data/pages/home.tsx | 2 +- 9 files changed, 25 insertions(+), 25 deletions(-) rename docs/build/{getting-started/testing.md => guides/smart-contracts/testing/intro.md} (87%) rename docs/{cadence/testing-framework.mdx => build/guides/smart-contracts/testing/testing-framework.md} (99%) rename docs/build/guides/smart-contracts/{ => testing}/testing.md (85%) diff --git a/docs/build/building-vs-other-chains.md b/docs/build/building-vs-other-chains.md index 2409f8b76f..59b35bf972 100644 --- a/docs/build/building-vs-other-chains.md +++ b/docs/build/building-vs-other-chains.md @@ -188,6 +188,6 @@ If you’re already familiar with blockchain development, here's a comparison be - [Flow Playground](https://play.flow.com/) provides basic experimentation on the web - [Cadence VSCode Extension](https://marketplace.visualstudio.com/items?itemName=onflow.cadence) is strongly suggested to install for local development - [Testing Smart Contracts](https://ethereum.org/en/developers/docs/smart-contracts/testing/) - - [Cadence testing framework](../cadence/testing-framework.mdx) enables native tests in Cadence. + - [Cadence testing framework](./guides/smart-contracts/testing/testing-framework.md) enables native tests in Cadence. - [overflow](https://github.com/bjartek/overflow) for testing in Go. - [js-testing](https://github.com/onflow/flow-js-testing) for testing in JS. \ No newline at end of file diff --git a/docs/build/getting-started/explore-more.mdx b/docs/build/getting-started/explore-more.mdx index 61a4dc4ff9..1bcfbbde23 100644 --- a/docs/build/getting-started/explore-more.mdx +++ b/docs/build/getting-started/explore-more.mdx @@ -16,7 +16,7 @@ Below are some additional tutorials to help you get started with Flow: { type: 'link', label: 'Flow App Quickstart', - href: '/guides/flow-app-quickstart', + href: '/build/guides/flow-app-quickstart', description: 'Simple walkthrough building a web3 app using the Flow Client Library (FCL)', customProps: { icon: , @@ -30,7 +30,7 @@ Below are some additional tutorials to help you get started with Flow: { type: 'link', label: 'Fungible Token Guide', - href: '/guides/fungible-token', + href: '/build/guides/fungible-token', description: 'Steps to create, deploy, mint, and transfer fungible tokens on Flow', customProps: { icon: , @@ -58,7 +58,7 @@ Below are some additional tutorials to help you get started with Flow: { type: 'link', label: 'Walkthrough Guides', - href: '/guides/flow-app-quickstart', + href: '/build/guides/flow-app-quickstart', description: 'Longer form guides to help you get started with Flow', customProps: { icon: , diff --git a/docs/build/guides/smart-contracts/deploying.md b/docs/build/guides/smart-contracts/deploying.md index 0e220010ce..cf7660fe9c 100644 --- a/docs/build/guides/smart-contracts/deploying.md +++ b/docs/build/guides/smart-contracts/deploying.md @@ -24,7 +24,7 @@ Anyone can deploy and update contracts on mainnet. Audits are encouraged but not ### Create and deploy a mainnet project The tool of choice is Flow CLI, there are quickstarts and guides that use Flow CLI, [Getting Started](../../getting-started/quickstarts/flow-cli) -- It is highly encouraged to test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow any additional guidelines set out here: [Smart Contract Testing Guidelines](./testing). +- It is highly encouraged to test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow any additional guidelines set out here: [Smart Contract Testing Guidelines](./testing/testing.md). - Follow the Flow CLI instructions to [Create a Project](../../../tools/flow-cli/index.md). You have the Flow CLI installed and ran `flow init` or `flow setup` in your project folder and generating a `flow.json` file - Mainnet account: You completed the mainnet account setup, (see above) and have your key pair and mainnet address ready. - [Deploy your project](../../../tools/flow-cli/deployment/deploy-project-contracts.md), notice that your account now has contracts deployed on mainnet. diff --git a/docs/build/getting-started/testing.md b/docs/build/guides/smart-contracts/testing/intro.md similarity index 87% rename from docs/build/getting-started/testing.md rename to docs/build/guides/smart-contracts/testing/intro.md index 4bd26b428d..9af66a2e9e 100644 --- a/docs/build/getting-started/testing.md +++ b/docs/build/guides/smart-contracts/testing/intro.md @@ -5,14 +5,14 @@ Testing is an essential part of smart contract development to ensure the correct ## Install Flow CLI -The [Flow CLI](../../tools/flow-cli/index.md) is the primary tool for developing, testing, and deploying smart contracts to the Flow network. +The [Flow CLI](../../../../tools/flow-cli/index.md) is the primary tool for developing, testing, and deploying smart contracts to the Flow network. -If you haven't installed the Flow CLI yet and have [homebrew](https://brew.sh/) installed, simply run `brew install flow-cli`. Alternatively, refer to the Flow CLI [installation instructions](../../tools/flow-cli/install.md). +If you haven't installed the Flow CLI yet and have [homebrew](https://brew.sh/) installed, simply run `brew install flow-cli`. Alternatively, refer to the Flow CLI [installation instructions](../../../../tools/flow-cli/install.md). ## Create a new project In your preferred code editor, create a new directory for your project and navigate to it in the terminal. Then -initialize a new Flow project by running the command `flow init`. This will create a `flow.json` file that contains the [project configuration](../../tools/flow-cli/flow.json/configuration.md). +initialize a new Flow project by running the command `flow init`. This will create a `flow.json` file that contains the [project configuration](../../../../tools/flow-cli/flow.json/configuration.md). ```bash mkdir test-cadence @@ -95,7 +95,7 @@ The Cadence testing framework provides various features and techniques for writi - [**Code Coverage**](https://github.com/m-Peter/flow-code-coverage): You can use the `--cover` flag with the `flow test` command to view code coverage results when running your tests. This allows you to identify areas of your code that are not adequately covered by your test inputs; - **Test Fixtures**: Test fixtures are reusable components that help you set up the initial state for your test cases. You can create test fixtures in Cadence by defining resource types and using them in your test functions; -- [**Assertions**](../../cadence/testing-framework.mdx#assertions): The testing framework provides built-in assertion functions, such as `assertEqual`, `beNil`, `beEmpty`, `contain`, to help you verify the expected behavior of your smart contracts; +- [**Assertions**](./testing-framework.md#assertions): The testing framework provides built-in assertion functions, such as `assertEqual`, `beNil`, `beEmpty`, `contain`, to help you verify the expected behavior of your smart contracts; - **Test Suites**: You can organize your test cases into test suites to improve the readability and maintainability of your test code. Test suites allow you to group related test cases and set up common test fixtures for all the tests in the suite. - [**Integration tests**](https://github.com/bjartek/overflow): You can use [Overflow tool](https://github.com/bjartek/overflow) to run integration tests against either an local emulator, testnet, mainnet or an in memory instance of the flow-emulator. @@ -103,9 +103,9 @@ By leveraging these advanced testing techniques, you can write more robust and r This is a basic example, and there are many more advanced features and techniques you can explore when working with the Cadence Testing Framework. -For more in-depth tutorials and documentation, refer to the official [Cadence language documentation](https://cadencelang.org/) and the [Flow CLI documentation](../../tools/flow-cli/index.md). +For more in-depth tutorials and documentation, refer to the official [Cadence language documentation](https://cadencelang.org/) and the [Flow CLI documentation](../../../../tools/flow-cli/index.md). ## References -- [Reference documentation for Cadence testing](../../cadence/testing-framework.mdx) +- [Reference documentation for Cadence testing](./testing-framework.md) - https://github.com/bjartek/overflow diff --git a/docs/cadence/testing-framework.mdx b/docs/build/guides/smart-contracts/testing/testing-framework.md similarity index 99% rename from docs/cadence/testing-framework.mdx rename to docs/build/guides/smart-contracts/testing/testing-framework.md index 1f2a7492a5..13c4ad7996 100644 --- a/docs/cadence/testing-framework.mdx +++ b/docs/build/guides/smart-contracts/testing/testing-framework.md @@ -7,7 +7,7 @@ The Cadence testing framework provides a convenient way to write tests for Caden This functionality is provided by the built-in `Test` contract. -The testing framework can only be used off-chain, e.g. by using the [Flow CLI](../tools/flow-cli). +The testing framework can only be used off-chain, e.g. by using the [Flow CLI](../../../../tools/flow-cli/index.md). Tests must be written in the form of a Cadence script. @@ -759,7 +759,7 @@ access(all) struct interface BlockchainBackend { ### Creating a blockchain A new blockchain instance can be created using the `Test.newEmulatorBlockchain` method. -It returns a `Blockchain` which is backed by a new [Flow Emulator](../tools/emulator) instance. +It returns a `Blockchain` which is backed by a new [Flow Emulator](../../../../tools/emulator/index.md) instance. ```cadence import Test @@ -1009,7 +1009,7 @@ An `Error` is returned if the contract deployment fails. Otherwise, a `nil` is r ### Configuring import addresses A common pattern in Cadence projects is to define the imports as file locations and specify the addresses -corresponding to each network in the [Flow CLI configuration file](../tools/flow-cli/flow.json/configuration.md#contracts). +corresponding to each network in the [Flow CLI configuration file](../../../../tools/flow-cli/flow.json/configuration.md#contracts). When writing tests for such a project, it may also require to specify the addresses to be used during the tests as well. However, during tests, since accounts are created dynamically and the addresses are also generated dynamically, specifying the addresses statically in a configuration file is not an option. @@ -1034,7 +1034,7 @@ access(all) struct Configuration { The `Blockchain.useConfiguration` is a run-time alternative for -[statically defining contract addresses in the flow.json config file](../tools/flow-cli/flow.json/configuration.md#advanced-format). +[statically defining contract addresses in the flow.json config file](../../../../tools/flow-cli/flow.json/configuration.md#advanced-format). The configurations can be specified during the test setup as a best-practice. diff --git a/docs/build/guides/smart-contracts/testing.md b/docs/build/guides/smart-contracts/testing/testing.md similarity index 85% rename from docs/build/guides/smart-contracts/testing.md rename to docs/build/guides/smart-contracts/testing/testing.md index c897846f8e..ef90c62247 100644 --- a/docs/build/guides/smart-contracts/testing.md +++ b/docs/build/guides/smart-contracts/testing/testing.md @@ -11,7 +11,7 @@ Testing is an essential part of the development workflow and code coverage is an Good test coverage is vital for assuring code quality. -Leverage [Flow emulator](../../../tools/emulator/index.md) to automate test runs. Test on Flow testnet. Include unit tests; to exercise each feature, and integration tests; to exercise the behavior of different parts of the project as a whole. +Leverage [Flow emulator](../../../../tools/emulator/index.md) to automate test runs. Test on Flow testnet. Include unit tests; to exercise each feature, and integration tests; to exercise the behavior of different parts of the project as a whole. The emulator can also provide [code coverage](https://github.com/m-Peter/flow-code-coverage#for-emulator) insights. @@ -39,20 +39,20 @@ In all three cases, the test code will need to deploy the contracts, configure a ### Cadence tests Cadence comes with built-in support for code coverage, as well as a native testing framework which allows developers to write their tests using Cadence. -This framework is bundled with the [Flow CLI](../../../tools/flow-cli/index.md) tool, which includes a dedicated command for running tests (`flow test`). +This framework is bundled with the [Flow CLI](../../../../tools/flow-cli/index.md) tool, which includes a dedicated command for running tests (`flow test`). You can find examples of Cadence tests in the following projects: [hybrid-custody](https://github.com/onflow/hybrid-custody/tree/main/test), [flow-nft](https://github.com/onflow/flow-nft/tree/master/tests), [flow-ft](https://github.com/onflow/flow-ft/tree/master/tests). -Visit the [documentation](../../../cadence/testing-framework.mdx) to view all the available features. +Visit the [documentation](./testing-framework.md) to view all the available features. The [Hybrid Custody](https://github.com/onflow/hybrid-custody#readme) project is a prime example which utilizes both the Cadence testing framework and code coverage in its CI. -![Hybrid Custody CI](hybrid-custody-ci.png) +![Hybrid Custody CI](../hybrid-custody-ci.png) There is also a [repository](https://github.com/m-Peter/flow-code-coverage#readme) which contains some sample contracts and their tests. -![Automated CI Coverage Report](codecov-in-pr.png) +![Automated CI Coverage Report](../codecov-in-pr.png) -![Coverage Report Visualization](codecov-insights.png) +![Coverage Report Visualization](../codecov-insights.png) The Cadence testing framework utilizes the emulator under the hood. @@ -87,5 +87,5 @@ Tests should also be runnable in automated environments (CI). You can use the [J Once you deployed your application to the testnet, you should record how your application handles non-trivial amounts of traffic to ensure there are no issues. -Get familiar with the [Cadence anti-patterns](../../../cadence/anti-patterns.md) to avoid avoid problematic or unintended behavior. +Get familiar with the [Cadence anti-patterns](../../../../cadence/anti-patterns.md) to avoid avoid problematic or unintended behavior. \ No newline at end of file diff --git a/docs/tools/flow-cli/tests/run-tests.md b/docs/tools/flow-cli/tests/run-tests.md index 1776871815..71eff6e0e8 100644 --- a/docs/tools/flow-cli/tests/run-tests.md +++ b/docs/tools/flow-cli/tests/run-tests.md @@ -41,7 +41,7 @@ Test results: "test_script.cdc" ``` -To learn more about writing tests in Cadence, take a look at the [Cadence testing framework](../../../cadence/testing-framework.mdx). +To learn more about writing tests in Cadence, take a look at the [Cadence testing framework](../../../build/guides/smart-contracts/testing/testing-framework.md). ## Flags diff --git a/docusaurus.config.js b/docusaurus.config.js index d2d92c426f..273a09d68e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -338,7 +338,7 @@ const config = { label: 'FCL', }, { - to: '/build/getting-started/testing', + to: '/build/guides/smart-contracts/testing/intro', label: 'Testing', }, { diff --git a/src/data/pages/home.tsx b/src/data/pages/home.tsx index 65c85bd9ee..ff2fbab9a3 100644 --- a/src/data/pages/home.tsx +++ b/src/data/pages/home.tsx @@ -11,7 +11,7 @@ const homepageStartProjectData: HomepageStartItemProps[] = [ { title: 'Developer Guides', text: 'Create your first dApp in just a few minutes', - link: '/guides/flow-app-quickstart', + link: '/build/guides/flow-app-quickstart', icon: 'quickstart', }, { From 1d3f3d9528b7cb32f2ca380a1137983032e9430f Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Mon, 6 Nov 2023 14:17:25 -0500 Subject: [PATCH 04/13] fix file name --- docs/build/guides/smart-contracts/deploying.md | 2 +- .../testing/{testing.md => testing-contracts.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/build/guides/smart-contracts/testing/{testing.md => testing-contracts.md} (100%) diff --git a/docs/build/guides/smart-contracts/deploying.md b/docs/build/guides/smart-contracts/deploying.md index cf7660fe9c..702f27ef45 100644 --- a/docs/build/guides/smart-contracts/deploying.md +++ b/docs/build/guides/smart-contracts/deploying.md @@ -24,7 +24,7 @@ Anyone can deploy and update contracts on mainnet. Audits are encouraged but not ### Create and deploy a mainnet project The tool of choice is Flow CLI, there are quickstarts and guides that use Flow CLI, [Getting Started](../../getting-started/quickstarts/flow-cli) -- It is highly encouraged to test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow any additional guidelines set out here: [Smart Contract Testing Guidelines](./testing/testing.md). +- It is highly encouraged to test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow any additional guidelines set out here: [Smart Contract Testing Guidelines](./testing/testing-contracts.md). - Follow the Flow CLI instructions to [Create a Project](../../../tools/flow-cli/index.md). You have the Flow CLI installed and ran `flow init` or `flow setup` in your project folder and generating a `flow.json` file - Mainnet account: You completed the mainnet account setup, (see above) and have your key pair and mainnet address ready. - [Deploy your project](../../../tools/flow-cli/deployment/deploy-project-contracts.md), notice that your account now has contracts deployed on mainnet. diff --git a/docs/build/guides/smart-contracts/testing/testing.md b/docs/build/guides/smart-contracts/testing/testing-contracts.md similarity index 100% rename from docs/build/guides/smart-contracts/testing/testing.md rename to docs/build/guides/smart-contracts/testing/testing-contracts.md From 69192e91294336ea7493dc6e928c301a55e78fc1 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Mon, 6 Nov 2023 18:27:58 -0500 Subject: [PATCH 05/13] fix content --- docs/build/building-vs-other-chains.md | 2 +- .../build/guides/smart-contracts/deploying.md | 2 +- docs/build/guides/smart-contracts/testing.md | 182 ++++++++++++++++++ .../guides/smart-contracts/testing/intro.md | 111 ----------- .../testing/testing-contracts.md | 91 --------- .../testing-framework.mdx} | 8 +- docs/tools/flow-cli/tests/run-tests.md | 2 +- docusaurus.config.js | 2 +- 8 files changed, 190 insertions(+), 210 deletions(-) create mode 100644 docs/build/guides/smart-contracts/testing.md delete mode 100644 docs/build/guides/smart-contracts/testing/intro.md delete mode 100644 docs/build/guides/smart-contracts/testing/testing-contracts.md rename docs/{build/guides/smart-contracts/testing/testing-framework.md => cadence/testing-framework.mdx} (99%) diff --git a/docs/build/building-vs-other-chains.md b/docs/build/building-vs-other-chains.md index 59b35bf972..2409f8b76f 100644 --- a/docs/build/building-vs-other-chains.md +++ b/docs/build/building-vs-other-chains.md @@ -188,6 +188,6 @@ If you’re already familiar with blockchain development, here's a comparison be - [Flow Playground](https://play.flow.com/) provides basic experimentation on the web - [Cadence VSCode Extension](https://marketplace.visualstudio.com/items?itemName=onflow.cadence) is strongly suggested to install for local development - [Testing Smart Contracts](https://ethereum.org/en/developers/docs/smart-contracts/testing/) - - [Cadence testing framework](./guides/smart-contracts/testing/testing-framework.md) enables native tests in Cadence. + - [Cadence testing framework](../cadence/testing-framework.mdx) enables native tests in Cadence. - [overflow](https://github.com/bjartek/overflow) for testing in Go. - [js-testing](https://github.com/onflow/flow-js-testing) for testing in JS. \ No newline at end of file diff --git a/docs/build/guides/smart-contracts/deploying.md b/docs/build/guides/smart-contracts/deploying.md index 702f27ef45..0229835eba 100644 --- a/docs/build/guides/smart-contracts/deploying.md +++ b/docs/build/guides/smart-contracts/deploying.md @@ -24,7 +24,7 @@ Anyone can deploy and update contracts on mainnet. Audits are encouraged but not ### Create and deploy a mainnet project The tool of choice is Flow CLI, there are quickstarts and guides that use Flow CLI, [Getting Started](../../getting-started/quickstarts/flow-cli) -- It is highly encouraged to test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow any additional guidelines set out here: [Smart Contract Testing Guidelines](./testing/testing-contracts.md). +- It is highly encouraged to test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow any additional guidelines set out here: [Smart Contract Testing Guidelines](./testing.md). - Follow the Flow CLI instructions to [Create a Project](../../../tools/flow-cli/index.md). You have the Flow CLI installed and ran `flow init` or `flow setup` in your project folder and generating a `flow.json` file - Mainnet account: You completed the mainnet account setup, (see above) and have your key pair and mainnet address ready. - [Deploy your project](../../../tools/flow-cli/deployment/deploy-project-contracts.md), notice that your account now has contracts deployed on mainnet. diff --git a/docs/build/guides/smart-contracts/testing.md b/docs/build/guides/smart-contracts/testing.md new file mode 100644 index 0000000000..c70eb3f92a --- /dev/null +++ b/docs/build/guides/smart-contracts/testing.md @@ -0,0 +1,182 @@ +--- +title: Testing Your Contracts +sidebar_label: Testing Your Contracts +description: Testing smart contract Guidelines +sidebar_position: 3 +sidebar_custom_props: + icon: 📝 +--- + +Testing is an essential part of smart contract development to ensure the correctness and reliability of your code. Cadence Testing Framework provides a convenient way to write tests for your programs, allowing you to verify the functionality and correctness of your smart contracts. + +## Install Flow CLI + +The [Flow CLI](../../../tools/flow-cli/index.md) is the primary tool for developing, testing, and deploying smart contracts to the Flow network. + +If you haven't installed the Flow CLI yet and have [homebrew](https://brew.sh/) installed, simply run `brew install flow-cli`. Alternatively, refer to the Flow CLI [installation instructions](../../../tools/flow-cli/install.md). + +## Create a new project + +In your preferred code editor, create a new directory for your project and navigate to it in the terminal. Then +initialize a new Flow project by running the command `flow init`. This will create a `flow.json` file that contains the [project configuration](../../../tools/flow-cli/flow.json/configuration.md). + +```bash +mkdir test-cadence +cd test-cadence +flow init +``` + +## Write a simple smart contract + +In your code editor, create a new file called `calculator.cdc` and add the following code: + +```cadence calculator.cdc +access(all) contract Calculator { + access(all) fun add(a: Int, b: Int): Int { + return a + b; + } + + access(all) fun subtract(a: Int, b: Int): Int { + return a - b; + } +} +``` + +## Add the smart contract to the config + +Run `flow config add contract` and add the created `calculator.cdc` contract to the config with the name as `Calculator`. This command adds your contract name and location under the `contracts` key in `flow.json`. + +``` +Enter name: Calculate +Enter contract file location: ./calculator.cdc +``` + +## Write unit test cases + +In the same directory, create a new file called `calculator_test.cdc` and add the following code: + +```cadence calculator_test.cdc +import Test +import "Calculator" // contract name from the previous step + +access(all) let calculator = Calculator() + +access(all) fun testAdd() { + Test.assertEqual(5, calculator.add(a: 2, b: 3)) +} + +access(all) fun testSubtract() { + Test.assertEqual(2, calculator.subtract(a: 5, b: 3)) +} + +``` + +This code +- imports the `Calculator` contract from the `calculator.cdc` file (according to `flow.json`); +- creates an `calculator` instance of the smart-contract; +- defines two test functions: `testAdd()` and `testSubtract()`; +- calls `add()` and `subtract()` methods with different input values respectively. + +## Running the test cases + +To run the test cases, use the following command in the terminal: + +```bash +flow test ./calculator_test.cdc +``` + +This command uses the Flow CLI to run the test cases and display the output. You should see the following output: + +``` +Test results: "./calculator_test.cdc" +- PASS: testAdd +- PASS: testSubtract +``` + +This output indicates that both test cases ran successfully, and the smart contract is functioning as expected. + +## Advanced Testing Techniques + +The Cadence testing framework provides various features and techniques for writing comprehensive test cases. Some of these include: + +- [**Code Coverage**](https://github.com/m-Peter/flow-code-coverage): You can use the `--cover` flag with the `flow test` command to view code coverage results when running your tests. This allows you to identify areas of your code that are not adequately covered by your test inputs; +- **Test Fixtures**: Test fixtures are reusable components that help you set up the initial state for your test cases. You can create test fixtures in Cadence by defining resource types and using them in your test functions; +- [**Assertions**](../../../cadence/testing-framework.mdx#assertions): The testing framework provides built-in assertion functions, such as `assertEqual`, `beNil`, `beEmpty`, `contain`, to help you verify the expected behavior of your smart contracts; +- **Test Suites**: You can organize your test cases into test suites to improve the readability and maintainability of your test code. Test suites allow you to group related test cases and set up common test fixtures for all the tests in the suite. +- [**Integration tests**](https://github.com/bjartek/overflow): You can use [Overflow tool](https://github.com/bjartek/overflow) to run integration tests against either an local emulator, testnet, mainnet or an in memory instance of the flow-emulator. + +By leveraging these advanced testing techniques, you can write more robust and reliable smart contracts in Cadence. In this example, we set up a basic testing environment, wrote a simple smart contract in Cadence, and created a test case to verify its functionality. We then used the Flow CLI to run the test case and confirm that the smart contract is working correctly. + +This is a basic example, and there are many more advanced features and techniques you can explore when working with the Cadence Testing Framework. + +For more in-depth tutorials and documentation, refer to the official [Cadence language documentation](https://cadencelang.org/) and the [Flow CLI documentation](../../../tools/flow-cli/index.md). + +## Writing Tests + +There are official SDKs/frameworks for Flow in Cadence, Go and JavaScript. + +In all three cases, the test code will need to deploy the contracts, configure accounts to interact with them and send transactions to them. It will then have to wait for the transactions to be sealed and check the results by catching exceptions, checking for events, and querying state using scripts. + +### Cadence tests + +Cadence comes with built-in support for code coverage, as well as a native testing framework which allows developers to write their tests using Cadence. +This framework is bundled with the [Flow CLI](../../../tools/flow-cli/index.md) tool, which includes a dedicated command for running tests (`flow test`). + +You can find examples of Cadence tests in the following projects: [hybrid-custody](https://github.com/onflow/hybrid-custody/tree/main/test), [flow-nft](https://github.com/onflow/flow-nft/tree/master/tests), [flow-ft](https://github.com/onflow/flow-ft/tree/master/tests). +Visit the [documentation](../../../cadence/testing-framework.mdx) to view all the available features. + +The [Hybrid Custody](https://github.com/onflow/hybrid-custody#readme) project is a prime example which utilizes both the Cadence testing framework and code coverage in its CI. + +![Hybrid Custody CI](./hybrid-custody-ci.png) + +There is also a [repository](https://github.com/m-Peter/flow-code-coverage#readme) which contains some sample contracts and their tests. + +![Automated CI Coverage Report](./codecov-in-pr.png) + +![Coverage Report Visualization](./codecov-insights.png) + + +The Cadence testing framework utilizes the emulator under the hood. + + +### Go Tests + +Tests in Go can be written using [flow-go-sdk](https://github.com/onflow/flow-go-sdk) and the go test command. + +You can find examples of Go tests in the following projects: [flow-core-contracts](https://github.com/onflow/flow-core-contracts/tree/master/lib/go/test), [flow-nft](https://github.com/onflow/flow-nft/tree/master/lib/go/test), [flow-ft](https://github.com/onflow/flow-ft/tree/master/lib/go/test). + + +These tests are tied to the emulator but can be refactored to run on testnet + + +### JavaScript Tests + +Tests in JavaScript can be written using [flow-js-testing](https://github.com/onflow/flow-js-testing). + +It is critical to test your applications and contracts thoroughly on the testnet as part of your road to the mainnet. Testing will help you understand how to create stable and robust applications using the Flow development stack. + +## Testing Your Application + +### Automated Testing of Contract Code + +All contracts should include test coverage for _all contract functions_. Make sure you've accounted for success and failure cases appropriately. + +Tests should also be runnable in automated environments (CI). You can use the [JavaScript testing framework](https://github.com/onflow/flow-js-testing) to create tests for your smart contract code. + +### Stress Testing Live Applications Before Mainnet + +Once you deployed your application to the testnet, you should record how your application handles non-trivial amounts of traffic to ensure there are no issues. + + +Get familiar with the [Cadence anti-patterns](../../../cadence/anti-patterns.md) to avoid avoid problematic or unintended behavior. + + + +## References + +- [Reference documentation for Cadence testing](../../../cadence/testing-framework.mdx) +- [Overflow](https://github.com/bjartek/overflow) is a powerful Golang-based DSL for efficient testing and execution of blockchain interactions +- projects that have good examples of robust test cases: + - [hybrid-custody](https://github.com/onflow/hybrid-custody/tree/main/test), + - [flow-nft](https://github.com/onflow/flow-nft/tree/master/tests), + - [flow-ft](https://github.com/onflow/flow-ft/tree/master/tests). diff --git a/docs/build/guides/smart-contracts/testing/intro.md b/docs/build/guides/smart-contracts/testing/intro.md deleted file mode 100644 index 9af66a2e9e..0000000000 --- a/docs/build/guides/smart-contracts/testing/intro.md +++ /dev/null @@ -1,111 +0,0 @@ - -# Introduction to Testing in Cadence - -Testing is an essential part of smart contract development to ensure the correctness and reliability of your code. Cadence Testing Framework provides a convenient way to write tests for your programs, allowing you to verify the functionality and correctness of your smart contracts. - -## Install Flow CLI - -The [Flow CLI](../../../../tools/flow-cli/index.md) is the primary tool for developing, testing, and deploying smart contracts to the Flow network. - -If you haven't installed the Flow CLI yet and have [homebrew](https://brew.sh/) installed, simply run `brew install flow-cli`. Alternatively, refer to the Flow CLI [installation instructions](../../../../tools/flow-cli/install.md). - -## Create a new project - -In your preferred code editor, create a new directory for your project and navigate to it in the terminal. Then -initialize a new Flow project by running the command `flow init`. This will create a `flow.json` file that contains the [project configuration](../../../../tools/flow-cli/flow.json/configuration.md). - -```bash -mkdir test-cadence -cd test-cadence -flow init -``` - -## Write a simple smart contract - -In your code editor, create a new file called `calculator.cdc` and add the following code: - -```cadence calculator.cdc -access(all) contract Calculator { - access(all) fun add(a: Int, b: Int): Int { - return a + b; - } - - access(all) fun subtract(a: Int, b: Int): Int { - return a - b; - } -} -``` - -## Add the smart contract to the config - -Run `flow config add contract` and add the created `calculator.cdc` contract to the config with the name as `Calculator`. This command adds your contract name and location under the `contracts` key in `flow.json`. - -``` -Enter name: Calculate -Enter contract file location: ./calculator.cdc -``` - -## Write unit test cases - -In the same directory, create a new file called `calculator_test.cdc` and add the following code: - -```cadence calculator_test.cdc -import Test -import "Calculator" // contract name from the previous step - -access(all) let calculator = Calculator() - -access(all) fun testAdd() { - Test.assertEqual(5, calculator.add(a: 2, b: 3)) -} - -access(all) fun testSubtract() { - Test.assertEqual(2, calculator.subtract(a: 5, b: 3)) -} - -``` - -This code -- imports the `Calculator` contract from the `calculator.cdc` file (according to `flow.json`); -- creates an `calculator` instance of the smart-contract; -- defines two test functions: `testAdd()` and `testSubtract()`; -- calls `add()` and `subtract()` methods with different input values respectively. - -## Running the test cases - -To run the test cases, use the following command in the terminal: - -```bash -flow test ./calculator_test.cdc -``` - -This command uses the Flow CLI to run the test cases and display the output. You should see the following output: - -``` -Test results: "./calculator_test.cdc" -- PASS: testAdd -- PASS: testSubtract -``` - -This output indicates that both test cases ran successfully, and the smart contract is functioning as expected. - -## Advanced Testing Techniques - -The Cadence testing framework provides various features and techniques for writing comprehensive test cases. Some of these include: - -- [**Code Coverage**](https://github.com/m-Peter/flow-code-coverage): You can use the `--cover` flag with the `flow test` command to view code coverage results when running your tests. This allows you to identify areas of your code that are not adequately covered by your test inputs; -- **Test Fixtures**: Test fixtures are reusable components that help you set up the initial state for your test cases. You can create test fixtures in Cadence by defining resource types and using them in your test functions; -- [**Assertions**](./testing-framework.md#assertions): The testing framework provides built-in assertion functions, such as `assertEqual`, `beNil`, `beEmpty`, `contain`, to help you verify the expected behavior of your smart contracts; -- **Test Suites**: You can organize your test cases into test suites to improve the readability and maintainability of your test code. Test suites allow you to group related test cases and set up common test fixtures for all the tests in the suite. -- [**Integration tests**](https://github.com/bjartek/overflow): You can use [Overflow tool](https://github.com/bjartek/overflow) to run integration tests against either an local emulator, testnet, mainnet or an in memory instance of the flow-emulator. - -By leveraging these advanced testing techniques, you can write more robust and reliable smart contracts in Cadence. In this example, we set up a basic testing environment, wrote a simple smart contract in Cadence, and created a test case to verify its functionality. We then used the Flow CLI to run the test case and confirm that the smart contract is working correctly. - -This is a basic example, and there are many more advanced features and techniques you can explore when working with the Cadence Testing Framework. - -For more in-depth tutorials and documentation, refer to the official [Cadence language documentation](https://cadencelang.org/) and the [Flow CLI documentation](../../../../tools/flow-cli/index.md). - -## References - -- [Reference documentation for Cadence testing](./testing-framework.md) -- https://github.com/bjartek/overflow diff --git a/docs/build/guides/smart-contracts/testing/testing-contracts.md b/docs/build/guides/smart-contracts/testing/testing-contracts.md deleted file mode 100644 index ef90c62247..0000000000 --- a/docs/build/guides/smart-contracts/testing/testing-contracts.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Testing Your Contracts -sidebar_label: Testing Your Contracts -description: Testing smart contract Guidelines -sidebar_position: 3 -sidebar_custom_props: - icon: 📝 ---- - -Testing is an essential part of the development workflow and code coverage is an important metric that can help developers view what percentage of all the possible code paths have been exercised during testing. -Good test coverage is vital for assuring code quality. - - -Leverage [Flow emulator](../../../../tools/emulator/index.md) to automate test runs. Test on Flow testnet. Include unit tests; to exercise each feature, and integration tests; to exercise the behavior of different parts of the project as a whole. -The emulator can also provide [code coverage](https://github.com/m-Peter/flow-code-coverage#for-emulator) insights. - - -Human-driven tests, in which individual testers work manually through user stories via the project's user interface or custom transactions, can also be performed locally. Tests with groups of testers can be performed similarly on testnet in a similar manner. - -Finally, unstructured closed testing with a limited audience on testnet can gain valuable information about performance and security by capturing usage data from more organic interaction with the project's smart contracts over days or weeks. - -## Testing Requirements - -It is suggested to follow the following best practices: - -- Every publicly exposed feature of a contract and its resources should have unit tests that check both for success with correct input _and_ for failure with incorrect input. - These tests should be capable of being run locally with the Flow emulator, with no or minimal extra resources or configuration, and with a single command. -- Each user story or workflow that uses the smart contracts should have an integration test that ensures that the series of steps required to complete it does so successfully with test data. - -Make sure you test all contracts - and the integration into your application extensively before proceeding to the mainnet. -You should aim to replicate all conditions as closely as possible to the usage patterns on mainnet. - -## Writing Tests - -There are official SDKs/frameworks for Flow in Cadence, Go and JavaScript. - -In all three cases, the test code will need to deploy the contracts, configure accounts to interact with them and send transactions to them. It will then have to wait for the transactions to be sealed and check the results by catching exceptions, checking for events, and querying state using scripts. - -### Cadence tests - -Cadence comes with built-in support for code coverage, as well as a native testing framework which allows developers to write their tests using Cadence. -This framework is bundled with the [Flow CLI](../../../../tools/flow-cli/index.md) tool, which includes a dedicated command for running tests (`flow test`). - -You can find examples of Cadence tests in the following projects: [hybrid-custody](https://github.com/onflow/hybrid-custody/tree/main/test), [flow-nft](https://github.com/onflow/flow-nft/tree/master/tests), [flow-ft](https://github.com/onflow/flow-ft/tree/master/tests). -Visit the [documentation](./testing-framework.md) to view all the available features. - -The [Hybrid Custody](https://github.com/onflow/hybrid-custody#readme) project is a prime example which utilizes both the Cadence testing framework and code coverage in its CI. - -![Hybrid Custody CI](../hybrid-custody-ci.png) - -There is also a [repository](https://github.com/m-Peter/flow-code-coverage#readme) which contains some sample contracts and their tests. - -![Automated CI Coverage Report](../codecov-in-pr.png) - -![Coverage Report Visualization](../codecov-insights.png) - - -The Cadence testing framework utilizes the emulator under the hood. - - -### Go Tests - -Tests in Go can be written using [flow-go-sdk](https://github.com/onflow/flow-go-sdk) and the go test command. - -You can find examples of Go tests in the following projects: [flow-core-contracts](https://github.com/onflow/flow-core-contracts/tree/master/lib/go/test), [flow-nft](https://github.com/onflow/flow-nft/tree/master/lib/go/test), [flow-ft](https://github.com/onflow/flow-ft/tree/master/lib/go/test). - - -These tests are tied to the emulator but can be refactored to run on testnet - - -### JavaScript Tests - -Tests in JavaScript can be written using [flow-js-testing](https://github.com/onflow/flow-js-testing). - -It is critical to test your applications and contracts thoroughly on the testnet as part of your road to the mainnet. Testing will help you understand how to create stable and robust applications using the Flow development stack. - -## Testing Your Application - -### Automated Testing of Contract Code - -All contracts should include test coverage for _all contract functions_. Make sure you've accounted for success and failure cases appropriately. - -Tests should also be runnable in automated environments (CI). You can use the [JavaScript testing framework](https://github.com/onflow/flow-js-testing) to create tests for your smart contract code. - -### Stress Testing Live Applications Before Mainnet - -Once you deployed your application to the testnet, you should record how your application handles non-trivial amounts of traffic to ensure there are no issues. - - -Get familiar with the [Cadence anti-patterns](../../../../cadence/anti-patterns.md) to avoid avoid problematic or unintended behavior. - \ No newline at end of file diff --git a/docs/build/guides/smart-contracts/testing/testing-framework.md b/docs/cadence/testing-framework.mdx similarity index 99% rename from docs/build/guides/smart-contracts/testing/testing-framework.md rename to docs/cadence/testing-framework.mdx index 13c4ad7996..1b34e73d7c 100644 --- a/docs/build/guides/smart-contracts/testing/testing-framework.md +++ b/docs/cadence/testing-framework.mdx @@ -7,7 +7,7 @@ The Cadence testing framework provides a convenient way to write tests for Caden This functionality is provided by the built-in `Test` contract. -The testing framework can only be used off-chain, e.g. by using the [Flow CLI](../../../../tools/flow-cli/index.md). +The testing framework can only be used off-chain, e.g. by using the [Flow CLI](../tools/flow-cli/index.md). Tests must be written in the form of a Cadence script. @@ -759,7 +759,7 @@ access(all) struct interface BlockchainBackend { ### Creating a blockchain A new blockchain instance can be created using the `Test.newEmulatorBlockchain` method. -It returns a `Blockchain` which is backed by a new [Flow Emulator](../../../../tools/emulator/index.md) instance. +It returns a `Blockchain` which is backed by a new [Flow Emulator](../tools/emulator/index.md) instance. ```cadence import Test @@ -1009,7 +1009,7 @@ An `Error` is returned if the contract deployment fails. Otherwise, a `nil` is r ### Configuring import addresses A common pattern in Cadence projects is to define the imports as file locations and specify the addresses -corresponding to each network in the [Flow CLI configuration file](../../../../tools/flow-cli/flow.json/configuration.md#contracts). +corresponding to each network in the [Flow CLI configuration file](../tools/flow-cli/flow.json/configuration.md#contracts). When writing tests for such a project, it may also require to specify the addresses to be used during the tests as well. However, during tests, since accounts are created dynamically and the addresses are also generated dynamically, specifying the addresses statically in a configuration file is not an option. @@ -1034,7 +1034,7 @@ access(all) struct Configuration { The `Blockchain.useConfiguration` is a run-time alternative for -[statically defining contract addresses in the flow.json config file](../../../../tools/flow-cli/flow.json/configuration.md#advanced-format). +[statically defining contract addresses in the flow.json config file](../tools/flow-cli/flow.json/configuration.md#advanced-format). The configurations can be specified during the test setup as a best-practice. diff --git a/docs/tools/flow-cli/tests/run-tests.md b/docs/tools/flow-cli/tests/run-tests.md index 71eff6e0e8..1776871815 100644 --- a/docs/tools/flow-cli/tests/run-tests.md +++ b/docs/tools/flow-cli/tests/run-tests.md @@ -41,7 +41,7 @@ Test results: "test_script.cdc" ``` -To learn more about writing tests in Cadence, take a look at the [Cadence testing framework](../../../build/guides/smart-contracts/testing/testing-framework.md). +To learn more about writing tests in Cadence, take a look at the [Cadence testing framework](../../../cadence/testing-framework.mdx). ## Flags diff --git a/docusaurus.config.js b/docusaurus.config.js index 273a09d68e..e944c8f0b4 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -338,7 +338,7 @@ const config = { label: 'FCL', }, { - to: '/build/guides/smart-contracts/testing/intro', + to: '/build/guides/smart-contracts/testing', label: 'Testing', }, { From de7384f75cfcb3a01b93bf7dd17a7f934cc5b1c0 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Mon, 6 Nov 2023 18:41:28 -0500 Subject: [PATCH 06/13] clean-up --- docs/references/_category_.json | 4 ---- docs/references/_category_.yml | 3 ++- package.json | 1 - sidebars.js | 2 -- tailwind.config.js | 1 - versioned_sidebars/version-stable-sidebars.json | 4 ---- yarn.lock | 5 ----- 7 files changed, 2 insertions(+), 18 deletions(-) delete mode 100644 docs/references/_category_.json diff --git a/docs/references/_category_.json b/docs/references/_category_.json deleted file mode 100644 index b8b4bbf41f..0000000000 --- a/docs/references/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "References", - "position": 5 - } \ No newline at end of file diff --git a/docs/references/_category_.yml b/docs/references/_category_.yml index c248541a0d..ab5d8aec2a 100644 --- a/docs/references/_category_.yml +++ b/docs/references/_category_.yml @@ -1 +1,2 @@ -label: Dive In \ No newline at end of file +label: References +position: 5 \ No newline at end of file diff --git a/package.json b/package.json index a8f4aa56c9..07c2852152 100644 --- a/package.json +++ b/package.json @@ -28,7 +28,6 @@ "@mdx-js/react": "^3.0.0", "@tailwindcss/aspect-ratio": "0.4.2", "@tailwindcss/forms": "0.5.6", - "@tailwindcss/line-clamp": "0.4.4", "@tailwindcss/typography": "0.5.10", "autoprefixer": "10.4.14", "clsx": "^1.2.1", diff --git a/sidebars.js b/sidebars.js index fff4a74227..56511c3675 100644 --- a/sidebars.js +++ b/sidebars.js @@ -18,9 +18,7 @@ const sidebars = { build: [{ type: 'autogenerated', dirName: 'build' }], nodeOps: [{ type: 'autogenerated', dirName: 'node-ops' }], tutorials: [{ type: 'autogenerated', dirName: 'tutorials' }], - guides: [{ type: 'autogenerated', dirName: 'guides' }], cadence: [{ type: 'autogenerated', dirName: 'cadence' }], - buildingOnFlow: [{ type: 'autogenerated', dirName: 'building-on-flow' }], tools: [{ type: 'autogenerated', dirName: 'tools' }], references: [{ type: 'autogenerated', dirName: 'references' }], communityResources: [ diff --git a/tailwind.config.js b/tailwind.config.js index db8d810523..5dda328377 100644 --- a/tailwind.config.js +++ b/tailwind.config.js @@ -143,7 +143,6 @@ module.exports = { plugins: [ require('@tailwindcss/typography'), require('@tailwindcss/forms'), - require('@tailwindcss/line-clamp'), require('@tailwindcss/aspect-ratio'), require('tailwind-scrollbar-hide'), ], diff --git a/versioned_sidebars/version-stable-sidebars.json b/versioned_sidebars/version-stable-sidebars.json index 09deb71352..3649c8400e 100644 --- a/versioned_sidebars/version-stable-sidebars.json +++ b/versioned_sidebars/version-stable-sidebars.json @@ -1,14 +1,10 @@ { - "concepts": [{ "type": "autogenerated", "dirName": "concepts" }], "overview": [{ "type": "autogenerated", "dirName": "overview" }], "architecture": [{ "type": "autogenerated", "dirName": "architecture" }], "build": [{ "type": "autogenerated", "dirName": "build" }], "nodeOps": [{ "type": "autogenerated", "dirName": "node-ops" }], - "gettingStarted": [{ "type": "autogenerated", "dirName": "getting-started" }], "tutorials": [{ "type": "autogenerated", "dirName": "tutorials" }], - "guides": [{ "type": "autogenerated", "dirName": "guides" }], "cadence": [{ "type": "autogenerated", "dirName": "cadence" }], - "buildingOnFlow": [{ "type": "autogenerated", "dirName": "building-on-flow" }], "tools": [{ "type": "autogenerated", "dirName": "tools" }], "references": [{ "type": "autogenerated", "dirName": "references" }], "communityResources": [ diff --git a/yarn.lock b/yarn.lock index 604a43f297..7790051d5f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2589,11 +2589,6 @@ dependencies: mini-svg-data-uri "^1.2.3" -"@tailwindcss/line-clamp@0.4.4": - version "0.4.4" - resolved "https://registry.yarnpkg.com/@tailwindcss/line-clamp/-/line-clamp-0.4.4.tgz#767cf8e5d528a5d90c9740ca66eb079f5e87d423" - integrity sha512-5U6SY5z8N42VtrCrKlsTAA35gy2VSyYtHWCsg1H87NU1SXnEfekTVlrga9fzUDrrHcGi2Lb5KenUWb4lRQT5/g== - "@tailwindcss/typography@0.5.10": version "0.5.10" resolved "https://registry.yarnpkg.com/@tailwindcss/typography/-/typography-0.5.10.tgz#2abde4c6d5c797ab49cf47610830a301de4c1e0a" From 4f317f6387f7efe034915f7a6080cfa390438c18 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Tue, 7 Nov 2023 09:42:06 -0500 Subject: [PATCH 07/13] add more examples --- docs/cadence/testing-framework.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/cadence/testing-framework.mdx b/docs/cadence/testing-framework.mdx index 1b34e73d7c..f2dc4ff2ea 100644 --- a/docs/cadence/testing-framework.mdx +++ b/docs/cadence/testing-framework.mdx @@ -1290,3 +1290,8 @@ access(all) fun testExample() { This [repository](https://github.com/m-Peter/flow-code-coverage) contains some functional examples that demonstrate most of the above features, both for contrived and real-world smart contracts. It also contains a detailed explanation on using code coverage from within the testing framework. + +These are other real world projects with tests: +- https://github.com/onflow/hybrid-custody/tree/main/test, +- https://github.com/onflow/flow-nft/tree/master/tests, +- https://github.com/onflow/flow-ft/tree/master/tests. From 6f8a127e6f16b16bbfcd1d1c8a5db4e237205312 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Tue, 7 Nov 2023 09:44:58 -0500 Subject: [PATCH 08/13] redirects --- vercel.json | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/vercel.json b/vercel.json index 8647f27a0e..288fad24f9 100644 --- a/vercel.json +++ b/vercel.json @@ -1175,6 +1175,26 @@ "source": "/getting-started", "destination": "/build/getting-started/app-architecture", "permanent": true + }, + { + "source": "/guides/:path*", + "destination": "/build/guides/:path*", + "permanent": true + }, + { + "source": "/next/guides/:path*", + "destination": "/next/build/guides/:path*", + "permanent": true + }, + { + "source": "/build/getting-started/testing", + "destination": "/build/guides/smart-contracts/testing", + "permanent": true + }, + { + "source": "/next/build/getting-started/testing", + "destination": "/next/build/guides/smart-contracts/testing", + "permanent": true } ] } \ No newline at end of file From 4792810ad87c72d1092b9d43dcbf6fe524309031 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Tue, 7 Nov 2023 11:01:31 -0500 Subject: [PATCH 09/13] fix link --- docs/build/guides/flow-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/guides/flow-cli.md b/docs/build/guides/flow-cli.md index d658f53687..808fd0c4d5 100644 --- a/docs/build/guides/flow-cli.md +++ b/docs/build/guides/flow-cli.md @@ -50,7 +50,7 @@ To install a specific version of Flow CLI newer than v0.42.0, append the version sh -ci "$(curl -fsSL https://raw.githubusercontent.com/onflow/flow-cli/master/install.sh)" -- v0.44.0 ``` -To install a version older than v0.42.0, refer to [Installing versions before 0.42.0](../tools/flow-cli/install.md#installing-versions-before-0420) below. +To install a version older than v0.42.0, refer to [Installing versions before 0.42.0](../../tools/flow-cli/install.md#installing-versions-before-0420) below. ## Windows From 4623a0de406c664b5e7054a0660a40aab2249982 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Thu, 9 Nov 2023 16:48:53 -0500 Subject: [PATCH 10/13] fix links --- docs/build/guides/smart-contracts/testing.md | 10 +++++----- docusaurus.config.js | 6 +----- sidebars.js | 1 - 3 files changed, 6 insertions(+), 11 deletions(-) diff --git a/docs/build/guides/smart-contracts/testing.md b/docs/build/guides/smart-contracts/testing.md index 6d3616535a..620b1d2151 100644 --- a/docs/build/guides/smart-contracts/testing.md +++ b/docs/build/guides/smart-contracts/testing.md @@ -11,13 +11,13 @@ Testing is an essential part of smart contract development to ensure the correct ## Install Flow CLI -The [Flow CLI](../../tools/flow-cli/index.md) is the primary tool for developing, testing, and deploying smart contracts to the Flow network. +The [Flow CLI](../../../tools/flow-cli/index.md) is the primary tool for developing, testing, and deploying smart contracts to the Flow network. -If you haven't installed the Flow CLI yet and have [homebrew](https://brew.sh/) installed, simply run `brew install flow-cli`. Alternatively, refer to the Flow CLI [installation instructions](../../tools/flow-cli/install.md). +If you haven't installed the Flow CLI yet and have [homebrew](https://brew.sh/) installed, simply run `brew install flow-cli`. Alternatively, refer to the Flow CLI [installation instructions](../../../tools/flow-cli/install.md). ## Create a new project -In your preferred code editor, create a new directory for your project and navigate to it in the terminal. Then initialize a new Flow project by running the command `flow init`. This will create a `flow.json` config file that contains the [project's configuration](../../tools/flow-cli/flow.json/configuration.md). +In your preferred code editor, create a new directory for your project and navigate to it in the terminal. Then initialize a new Flow project by running the command `flow init`. This will create a `flow.json` config file that contains the [project's configuration](../../../tools/flow-cli/flow.json/configuration.md). ```bash mkdir test-cadence @@ -213,7 +213,7 @@ Cadence comes with built-in support for code coverage, as well as a native testi This framework is bundled with the [Flow CLI](../../../tools/flow-cli/index.md) tool, which includes a dedicated command for running tests (`flow test`). You can find examples of Cadence tests in the following projects: [hybrid-custody](https://github.com/onflow/hybrid-custody/tree/main/test), [flow-nft](https://github.com/onflow/flow-nft/tree/master/tests), [flow-ft](https://github.com/onflow/flow-ft/tree/master/tests). -Visit the [documentation](../../../cadence/testing-framework.mdx) to view all the available features. +Visit the [documentation](https://cadence-lang.org/docs/testing-framework) to view all the available features. The [Hybrid Custody](https://github.com/onflow/hybrid-custody#readme) project is a prime example which utilizes both the Cadence testing framework and code coverage in its CI. @@ -258,7 +258,7 @@ Tests should also be runnable in automated environments (CI). You can use the [J Once you deployed your application to the testnet, you should record how your application handles non-trivial amounts of traffic to ensure there are no issues. -Get familiar with the [Cadence anti-patterns](../../../cadence/anti-patterns.md) to avoid avoid problematic or unintended behavior. +Get familiar with the [Cadence anti-patterns](https://cadence-lang.org/docs/anti-patterns) to avoid avoid problematic or unintended behavior. diff --git a/docusaurus.config.js b/docusaurus.config.js index 40d464eaa4..c199b53ba4 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -562,14 +562,10 @@ const config = { '@docusaurus/plugin-client-redirects', { createRedirects(existingPath) { - console.log({ existingPath }); if (existingPath.includes('/cadence')) { // Redirect from /docs/team/X to /community/X and /docs/support/X to /community/X return [ - existingPath.replace( - 'https://cadence-lang.org/docs/', - '/cadence', - ), + existingPath.replace('https://cadence-lang.org/docs', '/cadence'), ]; } return undefined; // Return a falsy value: no redirect created diff --git a/sidebars.js b/sidebars.js index 56511c3675..9ab759707b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -18,7 +18,6 @@ const sidebars = { build: [{ type: 'autogenerated', dirName: 'build' }], nodeOps: [{ type: 'autogenerated', dirName: 'node-ops' }], tutorials: [{ type: 'autogenerated', dirName: 'tutorials' }], - cadence: [{ type: 'autogenerated', dirName: 'cadence' }], tools: [{ type: 'autogenerated', dirName: 'tools' }], references: [{ type: 'autogenerated', dirName: 'references' }], communityResources: [ From 65e25335866803445ed5c528aa02c6d8ab567ad1 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Thu, 9 Nov 2023 17:09:44 -0500 Subject: [PATCH 11/13] add content --- docs/build/guides/smart-contracts/testing.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/build/guides/smart-contracts/testing.md b/docs/build/guides/smart-contracts/testing.md index 620b1d2151..2389f30218 100644 --- a/docs/build/guides/smart-contracts/testing.md +++ b/docs/build/guides/smart-contracts/testing.md @@ -199,7 +199,18 @@ By leveraging these advanced testing techniques, you can write more robust and r This is a basic example, and there are many more advanced features and techniques you can explore when working with the Cadence Testing Framework. -For more in-depth tutorials and documentation, refer to the official [Cadence language documentation](https://cadencelang.org/) and the [Flow CLI documentation](../../../tools/flow-cli/index.md). +For more in-depth tutorials and documentation, refer to the official [Cadence language documentation](https://cadence-lang.org/) and the [Flow CLI documentation](../../../tools/flow-cli/index.md). + +## Testing Requirements + +It is suggested to follow the following best practices: + +- Every publicly exposed feature of a contract and its resources should have unit tests that check both for success with correct input _and_ for failure with incorrect input. + These tests should be capable of being run locally with the Flow emulator, with no or minimal extra resources or configuration, and with a single command. +- Each user story or workflow that uses the smart contracts should have an integration test that ensures that the series of steps required to complete it does so successfully with test data. + +Make sure you test all contracts - and the integration into your application extensively before proceeding to the mainnet. +You should aim to replicate all conditions as closely as possible to the usage patterns on mainnet. ## Writing Tests From a32e3a22a3029546c77521a9ae20ef04b655be08 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Fri, 17 Nov 2023 19:11:19 -0500 Subject: [PATCH 12/13] addressing PR comments --- docs/build/guides/_category_.json | 2 +- docs/build/guides/flow-app-quickstart.md | 4 ++-- docs/build/guides/flow-cli.md | 7 +++---- docs/build/guides/fungible-token.md | 2 +- docs/build/guides/nft.md | 2 +- docs/build/guides/smart-contracts/_category_.yml | 2 +- docs/build/{ => guides/smart-contracts}/cadence.md | 2 +- docs/build/guides/smart-contracts/deploying.md | 2 +- docs/build/guides/smart-contracts/overview.md | 2 +- docs/build/guides/smart-contracts/testing.md | 2 +- docs/build/mobile/react-native-quickstart.md | 6 +++--- docs/references/core-contracts/flow-ft/index.md | 2 +- docs/references/core-contracts/flow-nft/index.md | 2 +- docs/tools/clients/fcl-js/index.md | 2 +- docs/tools/clients/unity-sdk/samples/ui-usage.md | 4 ++-- 15 files changed, 21 insertions(+), 22 deletions(-) rename docs/build/{ => guides/smart-contracts}/cadence.md (99%) diff --git a/docs/build/guides/_category_.json b/docs/build/guides/_category_.json index 137f6d06a9..5707fc1c26 100644 --- a/docs/build/guides/_category_.json +++ b/docs/build/guides/_category_.json @@ -1,4 +1,4 @@ { "label": "Guides", - "position": 1 + "position": 7 } diff --git a/docs/build/guides/flow-app-quickstart.md b/docs/build/guides/flow-app-quickstart.md index a3440c4564..1c64ccab04 100644 --- a/docs/build/guides/flow-app-quickstart.md +++ b/docs/build/guides/flow-app-quickstart.md @@ -2,7 +2,7 @@ title: Flow App Quickstart sidebar_label: Flow App Quickstart description: Building an application on Flow -sidebar_position: 2 +sidebar_position: 4 sidebar_custom_props: icon: 🏗️ --- @@ -27,7 +27,7 @@ This simple guide uses the "Hello World" scaffold, it is meant to provide all th FCL (aka Flow Client Library) wraps the logic needed to communicate with the Flow blockchain. It's a npm package, [More Information](../../tools/clients/fcl-js) -This guide assumes a good understanding of React. The concepts are easy to understand and apply to other libraries and framework. A strong understanding of Cadence (Flow's smart contract language) is not required. More information on Cadence, [learning the Cadence language](../cadence.md). +This guide assumes a good understanding of React. The concepts are easy to understand and apply to other libraries and framework. A strong understanding of Cadence (Flow's smart contract language) is not required. More information on Cadence, [learning the Cadence language](./smart-contracts/cadence.md). ### FCL concepts covered: diff --git a/docs/build/guides/flow-cli.md b/docs/build/guides/flow-cli.md index 808fd0c4d5..4d4a31cc1c 100644 --- a/docs/build/guides/flow-cli.md +++ b/docs/build/guides/flow-cli.md @@ -2,12 +2,10 @@ title: Flow CLI sidebar_label: Install Flow CLI description: Guide to installing and using Flow CLI -sidebar_position: 2 +sidebar_position: 5 --- -## Installation - -## macOS +## MacOS ### Homebrew @@ -28,6 +26,7 @@ sh -ci "$(curl -fsSL https://raw.githubusercontent.com/onflow/flow-cli/master/in To update, simply re-run the installation command above. It is currently not possible to install earlier versions of the Flow CLI with Homebrew. + ## Linux ### From a pre-built binary diff --git a/docs/build/guides/fungible-token.md b/docs/build/guides/fungible-token.md index 9a06c47067..f89ad8e13e 100644 --- a/docs/build/guides/fungible-token.md +++ b/docs/build/guides/fungible-token.md @@ -2,7 +2,7 @@ title: How to Create a Fungible Token on Flow sidebar_label: Create a Fungible Token description: Guide to creating a fungible token on Flow with the Flow CLI and Cadence. -sidebar_position: 4 +sidebar_position: 2 --- This article will guide you through the steps to create, deploy, mint, and transfer fungible tokens on Flow. diff --git a/docs/build/guides/nft.md b/docs/build/guides/nft.md index f32ce2e3e7..e3b06e0e92 100644 --- a/docs/build/guides/nft.md +++ b/docs/build/guides/nft.md @@ -2,7 +2,7 @@ title: How to Create an NFT Project on Flow sidebar_label: Create an NFT Project description: Guide to creating an NFT Project with the Flow CLI and Cadence. -sidebar_position: 5 +sidebar_position: 3 --- This tutorial dives into the technical steps required to craft an NFT on the Flow blockchain, providing developers with a clear roadmap from setup to deployment. diff --git a/docs/build/guides/smart-contracts/_category_.yml b/docs/build/guides/smart-contracts/_category_.yml index a68222e223..a39e52360b 100644 --- a/docs/build/guides/smart-contracts/_category_.yml +++ b/docs/build/guides/smart-contracts/_category_.yml @@ -1,5 +1,5 @@ label: Writing and Deploying Smart Contracts -position: 3 +position: 1 customProps: icon: 🧱 description: How to deploy smart contracts to mainnet and testnet diff --git a/docs/build/cadence.md b/docs/build/guides/smart-contracts/cadence.md similarity index 99% rename from docs/build/cadence.md rename to docs/build/guides/smart-contracts/cadence.md index a514aca4ca..d65ec10fee 100644 --- a/docs/build/cadence.md +++ b/docs/build/guides/smart-contracts/cadence.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 1 --- # Intro to Cadence diff --git a/docs/build/guides/smart-contracts/deploying.md b/docs/build/guides/smart-contracts/deploying.md index 0229835eba..bea3d34386 100644 --- a/docs/build/guides/smart-contracts/deploying.md +++ b/docs/build/guides/smart-contracts/deploying.md @@ -2,7 +2,7 @@ title: Deploying Contracts sidebar_label: Deploying Contracts description: Guidelines for deploying your project's contracts on Flow Mainnet -sidebar_position: 2 +sidebar_position: 3 sidebar_custom_props: icon: 🥇 --- diff --git a/docs/build/guides/smart-contracts/overview.md b/docs/build/guides/smart-contracts/overview.md index 4839876738..51212bfed1 100644 --- a/docs/build/guides/smart-contracts/overview.md +++ b/docs/build/guides/smart-contracts/overview.md @@ -1,7 +1,7 @@ --- title: Smart Contracts on Flow sidebar_title: Smart Contracts on Flow -sidebar_position: 1 +sidebar_position: 2 sidebar_label: Smart Contracts on Flow sidebar_custom_props: icon: 🛠️ diff --git a/docs/build/guides/smart-contracts/testing.md b/docs/build/guides/smart-contracts/testing.md index 2389f30218..ea0881503e 100644 --- a/docs/build/guides/smart-contracts/testing.md +++ b/docs/build/guides/smart-contracts/testing.md @@ -2,7 +2,7 @@ title: Testing Your Contracts sidebar_label: Testing Your Contracts description: Testing smart contract Guidelines -sidebar_position: 3 +sidebar_position: 4 sidebar_custom_props: icon: 📝 --- diff --git a/docs/build/mobile/react-native-quickstart.md b/docs/build/mobile/react-native-quickstart.md index d1bcc9914a..6ee099f44b 100644 --- a/docs/build/mobile/react-native-quickstart.md +++ b/docs/build/mobile/react-native-quickstart.md @@ -12,7 +12,7 @@ sidebar_position: 3 FCL-JS is the easiest way to start building decentralized applications. FCL (aka Flow Client Library) wraps much of the logic you'd have to write yourself on other blockchains. Follow this quick start and you'll have a solid overview of how to build a shippable dapp on Flow. -We're going to make an assumption that you know or understand React; however, the concepts should be easy to understand and transfer to another framework. While this tutorial will make use of Cadence (Flow's smart contract language), you do not need to know it. Instead, we recommend later diving into [learning the Cadence language](../cadence.md) once you've gotten the core FCL concepts down. +We're going to make an assumption that you know or understand React; however, the concepts should be easy to understand and transfer to another framework. While this tutorial will make use of Cadence (Flow's smart contract language), you do not need to know it. Instead, we recommend later diving into [learning the Cadence language](../guides/smart-contracts/cadence.md) once you've gotten the core FCL concepts down. In this tutorial, we are going to interact with an existing smart contract on Flow's testnet known as the [Profile Contract](https://testnet.flowdiver.io/contract/A.ba1132bc08f82fe2.Profile). Using this contract, we will create a new profile and edit the profile information, both via a wallet. In order to do this, the FCL concepts we'll cover are: @@ -301,9 +301,9 @@ Go ahead and click the "Send Query" button. You should see "No Profile." That's ## Initializing the Account -For the Profile contract to store a Profile in a user's account, it does so by initializing what is called a "resource." A resource is an ownable piece of data and functionality that can live in the user's account storage. This paradigm is known is as "resource-oriented-programming", a principle that is core to Cadence and differentiates its ownership model from other smart contract languages, [read more here](../cadence.md#intuiting-ownership-with-resources). Cadence makes it so that resources can only exist in one place at any time, they must be deliberately created, cannot be copied, and if desired, must be deliberately destroyed. +For the Profile contract to store a Profile in a user's account, it does so by initializing what is called a "resource." A resource is an ownable piece of data and functionality that can live in the user's account storage. This paradigm is known is as "resource-oriented-programming", a principle that is core to Cadence and differentiates its ownership model from other smart contract languages, [read more here](../guides/smart-contracts/cadence.md#intuiting-ownership-with-resources). Cadence makes it so that resources can only exist in one place at any time, they must be deliberately created, cannot be copied, and if desired, must be deliberately destroyed. -> There's a lot more to resources in Cadence than we'll cover in this guide, so if you'd like to know more, check out [this Cadence intro](../cadence.md). +> There's a lot more to resources in Cadence than we'll cover in this guide, so if you'd like to know more, check out [this Cadence intro](../guides/smart-contracts/cadence.md). To do this resource initialization on an account, we're going to add another function called `initAccount`. Inside of that function, we're going to add some Cadence code which says, *"Hey, does this account have a profile? If it doesn't, let's add one."* We do that using something called a "transaction." Transactions occur when you want to change the state of the blockchain, in this case, some data in a resource, in a specific account. And there is a cost (transaction fee) in order to do that; unlike a query. diff --git a/docs/references/core-contracts/flow-ft/index.md b/docs/references/core-contracts/flow-ft/index.md index 1454ac06f1..933344303a 100644 --- a/docs/references/core-contracts/flow-ft/index.md +++ b/docs/references/core-contracts/flow-ft/index.md @@ -13,7 +13,7 @@ Flow is a new blockchain for open worlds. Read more about it [here](https://flow Cadence is a new Resource-oriented programming language for developing smart contracts for the Flow Blockchain. -Read more about it [here](../../../build/cadence.md) and see its implementation [here](https://github.com/onflow/cadence) +Read more about it [here](../../../build/guides/smart-contracts/cadence.md) and see its implementation [here](https://github.com/onflow/cadence) We recommend that anyone who is reading this should have already completed the [Cadence Tutorials](https://cadence-lang.org/docs/tutorial/first-steps) diff --git a/docs/references/core-contracts/flow-nft/index.md b/docs/references/core-contracts/flow-nft/index.md index b692e2f223..6073e77292 100644 --- a/docs/references/core-contracts/flow-nft/index.md +++ b/docs/references/core-contracts/flow-nft/index.md @@ -9,7 +9,7 @@ contract on the [Flow blockchain](https://www.onflow.org/). ## What is Cadence? -[Cadence is the resource-oriented programming language](../../../build/cadence.md) +[Cadence is the resource-oriented programming language](../../../build/guides/smart-contracts/cadence.md) for developing smart contracts on Flow. Before reading this standard, diff --git a/docs/tools/clients/fcl-js/index.md b/docs/tools/clients/fcl-js/index.md index e706a2608e..24da93c7d7 100644 --- a/docs/tools/clients/fcl-js/index.md +++ b/docs/tools/clients/fcl-js/index.md @@ -118,7 +118,7 @@ See the [Flow App Quick Start](../../../build/guides/flow-app-quickstart.md). See the full [API Reference](./api.md) for all FCL functionality. -Learn Flow's smart contract language to build any script or transactions: [Cadence](../../../build/cadence.md). +Learn Flow's smart contract language to build any script or transactions: [Cadence](../../../build/guides/smart-contracts/cadence.md). Explore all of Flow [docs and tools](/). diff --git a/docs/tools/clients/unity-sdk/samples/ui-usage.md b/docs/tools/clients/unity-sdk/samples/ui-usage.md index 2da5e4733c..48eb5a1d8c 100644 --- a/docs/tools/clients/unity-sdk/samples/ui-usage.md +++ b/docs/tools/clients/unity-sdk/samples/ui-usage.md @@ -199,7 +199,7 @@ flow.AccountContractRemoved ### Scripts -Scripts are cadence code that you write and are executed on the blockchain. They can contain arguments and return values, and can interact with Smart Contracts. Scripts are read-only - they cannot mutate anything on the blockchain. Anything held in local memory is discarded when the script finishes execution. For more information on programming see [Cadence](../../../../build/cadence.md). +Scripts are cadence code that you write and are executed on the blockchain. They can contain arguments and return values, and can interact with Smart Contracts. Scripts are read-only - they cannot mutate anything on the blockchain. Anything held in local memory is discarded when the script finishes execution. For more information on programming see [Cadence](../../../../build/guides/smart-contracts/cadence.md). **Execute Simple Script At Latest Block** @@ -257,7 +257,7 @@ For more information about Transactions, see [cadence/language/transactions](htt For more information about Transaction signing, see [concepts/transaction-signing](../../../../build/basics/transactions.md#signing-a-transaction). -For more information about Cadence programming, see [cadence](../../../../build/cadence.md). +For more information about Cadence programming, see [cadence](../../../../build/guides/smart-contracts/cadence.md). **Signing In** From 3d5393cb580674af5af3a27687f472952178c3d0 Mon Sep 17 00:00:00 2001 From: Alex Ni <12097569+nialexsan@users.noreply.github.com> Date: Sun, 19 Nov 2023 17:54:55 -0500 Subject: [PATCH 13/13] fix links --- docs/references/run-and-secure/nodes/faq/developers.md | 2 +- docs/references/run-and-secure/nodes/faq/operators.md | 2 +- docs/tools/clients/fcl-js/index.mdx.txt | 2 +- docs/tools/clients/fcl-js/scripts.mdx | 2 +- docs/tools/clients/fcl-js/sdk-guidelines.mdx | 4 ++-- docs/tools/clients/flow-go-sdk/index.mdx | 4 ++-- docs/tools/vscode-extension/index.mdx | 2 +- 7 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/references/run-and-secure/nodes/faq/developers.md b/docs/references/run-and-secure/nodes/faq/developers.md index 3a7f05870b..457158eda4 100644 --- a/docs/references/run-and-secure/nodes/faq/developers.md +++ b/docs/references/run-and-secure/nodes/faq/developers.md @@ -37,7 +37,7 @@ You can query historical data and fetch contract code using the SDKs. Flow allows you to actively query the state of the blockchain using scripts written in the Cadence programming language. You can find out more about Cadence here: -[cadence](../../../../build/cadence.md) +[cadence](../../../../build/guides/smart-contracts/cadence.md) Running scripts and parsing their output is supported by the SDKs. diff --git a/docs/references/run-and-secure/nodes/faq/operators.md b/docs/references/run-and-secure/nodes/faq/operators.md index 80a1376ddc..2e322d435f 100644 --- a/docs/references/run-and-secure/nodes/faq/operators.md +++ b/docs/references/run-and-secure/nodes/faq/operators.md @@ -41,7 +41,7 @@ You can query historical data and fetch contract code using the SDKs. Flow allows you to actively query the state of the blockchain using scripts written in the Cadence programming language. You can find out more about Cadence here: -[cadence](../../../../build/cadence.md) +[cadence](../../../../build/guides/smart-contracts/cadence.md) Running scripts and parsing their output is supported by the SDKs. diff --git a/docs/tools/clients/fcl-js/index.mdx.txt b/docs/tools/clients/fcl-js/index.mdx.txt index 24f8c5d48f..8f171c6ad9 100644 --- a/docs/tools/clients/fcl-js/index.mdx.txt +++ b/docs/tools/clients/fcl-js/index.mdx.txt @@ -132,7 +132,7 @@ See the [Flow App Quick Start](../../guides/flow-app-quickstart.mdx). See the full [API Reference](./api.md) for all FCL functionality. -Learn Flow's smart contract language to build any script or transactions: [Cadence](../../../build/cadence.md). +Learn Flow's smart contract language to build any script or transactions: [Cadence](../../../build/guides/smart-contracts/cadence.md). Explore all of Flow [docs and tools](/). diff --git a/docs/tools/clients/fcl-js/scripts.mdx b/docs/tools/clients/fcl-js/scripts.mdx index 854cc335da..5fb4a77855 100644 --- a/docs/tools/clients/fcl-js/scripts.mdx +++ b/docs/tools/clients/fcl-js/scripts.mdx @@ -29,7 +29,7 @@ console.log(response) // 3 ### A more complicated Script -Things like [Resources](../../../build/cadence.md#resources) and [Structs](../../../build/cadence.md#structures) are fairly common place in Cadence. +Things like [Resources](../../../build/guides/smart-contracts/cadence.md#resources) and [Structs](../../../build/guides/smart-contracts/cadence.md#structures) are fairly common place in Cadence. In the following code snippet, our script defines a struct called `Point`, it then returns a list of them. diff --git a/docs/tools/clients/fcl-js/sdk-guidelines.mdx b/docs/tools/clients/fcl-js/sdk-guidelines.mdx index 4a25d86485..b5ec4b62eb 100644 --- a/docs/tools/clients/fcl-js/sdk-guidelines.mdx +++ b/docs/tools/clients/fcl-js/sdk-guidelines.mdx @@ -279,7 +279,7 @@ Transaction data is composed and signed with help of the SDK. The signed payload ## Transactions A transaction is nothing more than a signed set of data that includes script code which are instructions on how to mutate the network state and properties that define and limit it's execution. All these properties are explained bellow. -📖 **Script** field is the portion of the transaction that describes the state mutation logic. On Flow, transaction logic is written in [Cadence](../../../build/cadence.md). Here is an example transaction script: +📖 **Script** field is the portion of the transaction that describes the state mutation logic. On Flow, transaction logic is written in [Cadence](../../../build/guides/smart-contracts/cadence.md). Here is an example transaction script: ``` transaction(greeting: String) { execute { @@ -315,7 +315,7 @@ transaction { ``` 📖 **Gas limit** is the limit on the amount of computation a transaction requires, and it will abort if it exceeds its gas limit. -Cadence uses metering to measure the number of operations per transaction. You can read more about it in the [Cadence documentation](../../../build/cadence.md). +Cadence uses metering to measure the number of operations per transaction. You can read more about it in the [Cadence documentation](../../../build/guides/smart-contracts/cadence.md). The gas limit depends on the complexity of the transaction script. Until dedicated gas estimation tooling exists, it's best to use the emulator to test complex transactions and determine a safe limit. diff --git a/docs/tools/clients/flow-go-sdk/index.mdx b/docs/tools/clients/flow-go-sdk/index.mdx index a582b032f1..b7e26359a0 100644 --- a/docs/tools/clients/flow-go-sdk/index.mdx +++ b/docs/tools/clients/flow-go-sdk/index.mdx @@ -510,7 +510,7 @@ Executing a transaction requires couple of steps: A transaction is nothing more than a signed set of data that includes script code which are instructions on how to mutate the network state and properties that define and limit it's execution. All these properties are explained bellow. -📖 **Script** field is the portion of the transaction that describes the state mutation logic. On Flow, transaction logic is written in [Cadence](../../../build/cadence.md). Here is an example transaction script: +📖 **Script** field is the portion of the transaction that describes the state mutation logic. On Flow, transaction logic is written in [Cadence](../../../build/guides/smart-contracts/cadence.md). Here is an example transaction script: ``` transaction(greeting: String) { @@ -549,7 +549,7 @@ transaction { ``` 📖 **Gas limit** is the limit on the amount of computation a transaction requires, and it will abort if it exceeds its gas limit. -Cadence uses metering to measure the number of operations per transaction. You can read more about it in the [Cadence documentation](../../../build/cadence.md). +Cadence uses metering to measure the number of operations per transaction. You can read more about it in the [Cadence documentation](../../../build/guides/smart-contracts/cadence.md). The gas limit depends on the complexity of the transaction script. Until dedicated gas estimation tooling exists, it's best to use the emulator to test complex transactions and determine a safe limit. diff --git a/docs/tools/vscode-extension/index.mdx b/docs/tools/vscode-extension/index.mdx index 8bcf23742f..7c37fa6370 100644 --- a/docs/tools/vscode-extension/index.mdx +++ b/docs/tools/vscode-extension/index.mdx @@ -2,7 +2,7 @@ title: Cadence VS Code Extension --- -This extension integrates [Cadence](../../build/cadence.md), the resource-oriented smart contract programming language of [Flow](https://www.onflow.org/), into [Visual Studio Code](https://code.visualstudio.com/). +This extension integrates [Cadence](../../build/guides/smart-contracts/cadence.md), the resource-oriented smart contract programming language of [Flow](https://www.onflow.org/), into [Visual Studio Code](https://code.visualstudio.com/). It provides features like syntax highlighting, type checking, code completion, etc. Note that most editing features (type checking, code completion, etc.) are implemented in the [Cadence Language Server](https://github.com/onflow/cadence/tree/master/languageserver).