diff --git a/docs/build/getting-started/flow-cli.md b/docs/build/getting-started/flow-cli.md
index ee4b8d9143..9d2f98ab67 100644
--- a/docs/build/getting-started/flow-cli.md
+++ b/docs/build/getting-started/flow-cli.md
@@ -50,6 +50,12 @@ Inside the `cadence/contracts` directory, you'll find a `Counter.cdc` file. This
 
 Next, `cd` into your new project directory.
 
+:::info
+
+For additional details on how `flow.json` is configured, review the [configuration docs].
+
+:::
+
 ### Running the Tests
 
 To run the example test for the `Counter` contract located in `cadence/tests`, you can run:
@@ -58,9 +64,9 @@ To run the example test for the `Counter` contract located in `cadence/tests`, y
 flow test
 ```
 
-:::info
+:::tip
 
-For additional details on how `flow.json` is configured, review the [configuration docs].
+For a more detailed guide on running Cadence tests, check out the [tests documentation](../../tools/flow-cli/tests.md).
 
 :::
 
diff --git a/docs/tools/flow-cli/tests.md b/docs/tools/flow-cli/tests.md
new file mode 100644
index 0000000000..c5d83a4c08
--- /dev/null
+++ b/docs/tools/flow-cli/tests.md
@@ -0,0 +1,227 @@
+---
+title: Running Cadence Tests
+sidebar_label: Running Cadence Tests
+description: How to run Cadence tests from the CLI
+sidebar_position: 11
+---
+
+The Flow CLI provides a straightforward command to execute Cadence tests, enabling developers to validate their scripts and smart contracts effectively.
+
+To run all tests in your project, simply use:
+
+```shell
+flow test
+```
+
+The `flow test` command automatically discovers and runs all test scripts in your project that end with `_test.cdc`.
+
+> **Note:** The `test` command requires a properly initialized configuration. If you haven’t set up your Flow project yet, refer to the [flow init](flow.json/initialize-configuration.md) guide for assistance.
+
+## Prerequisites
+
+Before running your tests, ensure that your contracts are properly configured in your `flow.json` file, including any necessary testing aliases.
+
+### Setting Up Testing Aliases in Contracts
+
+If your tests involve deploying or interacting with contracts, you need to add your contracts to the `contracts` section in the `flow.json` configuration file. Specifically, include the contract name, source location, and an address alias for the `testing` environment.
+
+Example `flow.json` configuration:
+
+```json
+{
+  "contracts": {
+    "Counter": {
+      "source": "cadence/contracts/Counter.cdc",
+      "aliases": {
+        "testing": "0x0000000000000007"
+      }
+    }
+  },
+  "networks": {
+    // ... your network configurations
+  },
+  "accounts": {
+    // ... your account configurations
+  },
+  "deployments": {
+    // ... your deployment configurations
+  }
+}
+```
+
+For the `testing` alias, you can use one of the following addresses:
+
+- `0x0000000000000005`
+- `0x0000000000000006`
+- `0x0000000000000007`
+- `0x0000000000000008`
+- `0x0000000000000009`
+- `0x000000000000000A`
+- `0x000000000000000B`
+- `0x000000000000000C`
+- `0x000000000000000D`
+- `0x000000000000000E`
+
+> **Note**: For more information on setting up contracts and aliases, refer to the [Flow CLI Configuration](flow.json/initialize-configuration.md) documentation.
+
+## Example Usage
+
+Assuming you have a test script named `test_script_test.cdc` in your project directory, which verifies the functionality of a Cadence script executed in the testing environment:
+
+```cadence
+// test_script_test.cdc
+import Test
+
+access(all) let blockchain = Test.newEmulatorBlockchain()
+
+access(all) fun testSumOfTwo() {
+    let scriptResult = blockchain.executeScript(
+        "access(all) fun main(a: Int, b: Int): Int { return a + b }",
+        [2, 3]
+    )
+
+    Test.expect(scriptResult, Test.beSucceeded())
+
+    let sum = scriptResult.returnValue! as! Int
+    Test.assertEqual(5, sum)
+}
+```
+
+This script defines a single test case, `testSumOfTwo`, which checks if a Cadence script that adds two integers `(a + b)` works as expected. The test passes if the result matches the expected value of `5`.
+
+You can run all tests in your project using the CLI:
+
+```shell
+$ flow test
+```
+
+The Flow CLI will discover all test scripts ending with `_test.cdc` and execute them. The results will be displayed in the terminal:
+
+```shell
+Test results:
+- PASS: test_script_test.cdc > testSumOfTwo
+```
+
+To learn more about writing tests in Cadence, visit the [Cadence Testing Framework](../../build/smart-contracts/testing.md) documentation.
+
+---
+
+### Running Specific Tests
+
+If you wish to run a specific test script rather than all tests, you can provide the path to the test file:
+
+```shell
+flow test path/to/your/test_script_test.cdc
+```
+
+This will execute only the tests contained in the specified file.
+
+---
+
+## Flags
+
+The `flow test` command supports several flags that provide additional functionality for managing test execution and coverage reporting.
+
+### **Coverage Report**
+
+- **Flag:** `--cover`
+- **Default:** `false`
+
+The `--cover` flag calculates the coverage of the code being tested, helping you identify untested parts of your scripts and contracts.
+
+```shell
+$ flow test --cover
+```
+
+Sample output:
+
+```shell
+Test results:
+- PASS: test_script_test.cdc > testSumOfTwo
+Coverage: 96.5% of statements
+```
+
+---
+
+### Coverage Report Output File
+
+- **Flag:** `--coverprofile`
+- **Valid Inputs:** A valid filename with extension `.json` or `.lcov`
+- **Default:** `"coverage.json"`
+
+Use the `--coverprofile` flag to specify the output file for the coverage report.
+
+Example:
+
+```shell
+$ flow test --cover --coverprofile="coverage.lcov"
+```
+
+The generated coverage file can then be inspected:
+
+```shell
+$ cat coverage.lcov
+```
+
+### Coverage Code Type
+
+- **Flag:** `--covercode`
+- **Valid Inputs:** `"all"` (default) or `"contracts"`
+- **Default:** `"all"`
+
+The `--covercode` flag lets you limit the coverage report to specific types of code. Setting the value to `"contracts"` excludes scripts and transactions from the coverage analysis.
+
+```shell
+$ flow test --cover --covercode="contracts"
+```
+
+Sample output when no contracts are present:
+
+```shell
+Test results:
+- PASS: test_script_test.cdc > testSumOfTwo
+There are no statements to cover
+```
+
+> **Note:** In this example, the coverage report is empty because the `--covercode` flag is set to `"contracts"`, and the test script only contains scripts, not contracts.
+
+### Random Execution of Test Cases
+
+- **Flag:** `--random`
+- **Default:** `false`
+
+Use the `--random` flag to execute test cases in a random order. This can help identify issues that may arise due to test dependencies or the order in which tests are run.
+
+```shell
+flow test --random
+```
+
+### Seed for Random Execution
+
+- **Flag:** `--seed`
+- **Default:** `0`
+
+Use the `--seed` flag to specify a seed value for the random execution order of test cases. This allows you to reproduce a specific random order by using the same seed value, which is helpful for debugging flaky tests.
+
+```shell
+flow test --seed=12345
+```
+
+> **Note:** If both `--random` and `--seed` are provided, the `--random` flag will be ignored, and the seed value from `--seed` will be used for randomization.
+
+---
+
+### Run Specific Test by Name
+
+- **Flag:** `--name`
+- **Default:** `""` (empty string)
+
+Use the `--name` flag to run only tests that match the given name. This is useful when you want to execute a specific test function within your test scripts.
+
+```shell
+flow test --name=testSumOfTwo
+```
+
+This command will run only the test function named `testSumOfTwo` across all test scripts that contain it.
+
+To dive deeper into testing the functionality of your Cadence scripts and contracts, explore the [Cadence Testing Framework](https://cadence-lang.org/docs/testing-framework) documentation.
\ No newline at end of file
diff --git a/docs/tools/flow-cli/tests/_category_.json b/docs/tools/flow-cli/tests/_category_.json
deleted file mode 100644
index b6f8c563b2..0000000000
--- a/docs/tools/flow-cli/tests/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-  "label": "Tests",
-  "position": 13
-}
\ 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
deleted file mode 100644
index 3e3b6b8840..0000000000
--- a/docs/tools/flow-cli/tests/run-tests.md
+++ /dev/null
@@ -1,96 +0,0 @@
----
-title: Run Cadence tests
-description: How to run Cadence tests from the command line
-sidebar_position: 11
----
-
-The Flow CLI provides a command to run Cadence tests. 
-
-```shell
-flow test /path/to/test_script.cdc
-```
-
-⚠️ The `test` command expects configuration to be initialized. See [flow init](../flow.json/initialize-configuration.md) command.
-
-## Example Usage
-
-A simple Cadence script `test_script.cdc`, which has a test case for running a cadence script on-chain:
-```cadence
-import Test
-
-access(all) let blockchain = Test.newEmulatorBlockchain()
-
-access(all) fun testSumOfTwo() {
-    let scriptResult = blockchain.executeScript(
-        "access(all) fun main(a: Int, b: Int): Int { return a + b }",
-        [2, 3]
-    )
-
-    Test.expect(scriptResult, Test.beSucceeded())
-
-    let sum = scriptResult.returnValue! as! Int
-    Test.assertEqual(5, sum)
-}
-```
-The above test-script can be run with the CLI as follows, and the test results will be printed on the console.
-```shell
-$ flow test test_script.cdc
-
-Test results: "test_script.cdc"
-- PASS: testSumOfTwo
-
-```
-
-To learn more about writing tests in Cadence, take a look at the [Cadence testing framework](../../../build/smart-contracts/testing.md).
-
-## Flags
-
-### Coverage
-
-- Flag: `--cover`
-- Default: `false`
-
-Use the `cover` flag to calculate coverage report for the code being tested.
-```shell
-$ flow test --cover test_script.cdc
-
-Test results: "test_script.cdc"
-- PASS: testSumOfTwo
-Coverage: 96.5% of statements
-
-```
-
-### Coverage Report File
-
-- Flag: `--coverprofile`
-- Valid inputs: valid filename and extension
-- Default: `"coverage.json"`
-
-Use the `coverprofile` to specify the filename where the calculated coverage report is to be written. Supported filename extensions are `.json` and `.lcov`.
-```shell
-$ flow test --cover test_script.cdc
-
-$ cat coverage.json
-
-$ flow test --cover --coverprofile="coverage.lcov" test_script.cdc
-
-$ cat coverage.lcov
-```
-
-### Coverage Code Type
-
-- Flag: `--covercode`
-- Valid inputs: `"all"`, `"contracts"`
-- Default: `"all"`
-
-Use the `covercode` flag to calculate coverage report only for certain types of code. A value of `"contracts"` will exclude scripts and transactions from the coverage report.
-```shell
-$ flow test --cover --covercode="contracts" test_script.cdc
-
-Test results: "tests/test_script.cdc"
-- PASS: testSumOfTwo
-There are no statements to cover
-```
-
-Since we did not use any contracts in our sample test script, there is no coverage percentage to be reported.
-
diff --git a/vercel.json b/vercel.json
index 9b7fca4b19..9352f4601a 100644
--- a/vercel.json
+++ b/vercel.json
@@ -1277,6 +1277,11 @@
       "source": "/evm/vm-bridge",
       "destination": "/evm/cadence/vm-bridge",
       "permanent": true
+    },
+    {
+      "source": "/tools/flow-cli/tests/run-tests",
+      "destination": "/tools/flow-cli/tests",
+      "permanent": true
     }
   ]
 }
\ No newline at end of file