From b3709ee6356af485ea294517f546a70b1bf2f2e5 Mon Sep 17 00:00:00 2001
From: gnkz <gnkz.dev@gmail.com>
Date: Wed, 22 Nov 2023 16:20:47 +0100
Subject: [PATCH] docs: forks examples

---
 .github/workflows/forge.yml              |  2 +-
 docs/src/examples/events/example.md      |  1 -
 docs/src/examples/forks/example.md       | 25 ++++++++++++++++++++++++
 docs/src/examples/fs/example.md          |  5 ++++-
 docs/src/examples/results/example.md     |  8 ++++----
 docs/src/modules/forks.md                | 16 +--------------
 test/examples/forks/ForksExample01.t.sol | 18 +++++++++++++++++
 7 files changed, 53 insertions(+), 22 deletions(-)
 create mode 100644 docs/src/examples/forks/example.md
 create mode 100644 test/examples/forks/ForksExample01.t.sol

diff --git a/.github/workflows/forge.yml b/.github/workflows/forge.yml
index 7a3b69a5..a8f2ee17 100644
--- a/.github/workflows/forge.yml
+++ b/.github/workflows/forge.yml
@@ -22,7 +22,7 @@ jobs:
       - name: Build image
         run: docker build . -t nomoixyz/vulcan-test-suite
       - name: Run tests
-        run: docker run --rm nomoixyz/vulcan-test-suite
+        run: docker run --rm nomoixyz/vulcan-test-suite --no-match-path 'test/examples/**/*'
   format:
     name: Check format
     runs-on: ubuntu-latest
diff --git a/docs/src/examples/events/example.md b/docs/src/examples/events/example.md
index 8ae4b5fb..13f4d9b4 100644
--- a/docs/src/examples/events/example.md
+++ b/docs/src/examples/events/example.md
@@ -4,7 +4,6 @@
 Logging events and reading events topics and data
 
 ```solidity
-//// SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
 
 import {Test, expect, events, Log} from "vulcan/test.sol";
diff --git a/docs/src/examples/forks/example.md b/docs/src/examples/forks/example.md
new file mode 100644
index 00000000..0f02e446
--- /dev/null
+++ b/docs/src/examples/forks/example.md
@@ -0,0 +1,25 @@
+## Examples
+### How to use forks
+
+How to use forks. This example assumes there is a JSON RPC server running at `localhost:8545`
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, vulcan} from "vulcan/test.sol";
+import {forks, Fork} from "vulcan/test/Forks.sol";
+import {ctx} from "vulcan/test/Context.sol";
+
+contract ForksExample is Test {
+    string constant RPC_URL = "http://localhost:8545";
+
+    function test() external {
+        forks.create(RPC_URL).select();
+
+        expect(block.chainid).toEqual(31337);
+    }
+}
+
+```
+
diff --git a/docs/src/examples/fs/example.md b/docs/src/examples/fs/example.md
index c4cbfe33..b0ed539f 100644
--- a/docs/src/examples/fs/example.md
+++ b/docs/src/examples/fs/example.md
@@ -73,7 +73,10 @@ Obtain metadata and check if file exists
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
 
-import {Test, expect, fs, BoolResult, FsMetadataResult} from "vulcan/test.sol";
+import {Test} from "vulcan/test.sol";
+import {expect} from "vulcan/test/Expect.sol";
+import {fs, FsMetadataResult} from "vulcan/test/Fs.sol";
+import {BoolResult} from "vulcan/test/Result.sol";
 
 contract FsExample is Test {
     // These files are available only on the context of vulcan
diff --git a/docs/src/examples/results/example.md b/docs/src/examples/results/example.md
index 2dda4f8b..c9178d53 100644
--- a/docs/src/examples/results/example.md
+++ b/docs/src/examples/results/example.md
@@ -7,7 +7,9 @@ Different methods of getting the underlyng value of a `Result`
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
 
-import {Test, expect, StringResult, Ok} from "vulcan/test.sol";
+import {Test, expect, StringResult} from "vulcan/test.sol";
+// This import is just to demonstration, it's not meant to be imported on projects using Vulcan
+import {Ok} from "vulcan/_internal/Result.sol";
 
 contract ResultExample is Test {
     function test() external {
@@ -48,9 +50,7 @@ contract ResultExample is Test {
         CommandResult result = commands.run(["asdf12897u391723"]);
 
         // Use unwrap to revert with the default error message
-        ctx.expectRevert(
-            "The command was not executed: \"Failed to execute command: No such file or directory (os error 2)\""
-        );
+        ctx.expectRevert();
         result.unwrap();
 
         // Use expect to revert with a custom error message
diff --git a/docs/src/modules/forks.md b/docs/src/modules/forks.md
index cc53cdec..d9b50475 100644
--- a/docs/src/modules/forks.md
+++ b/docs/src/modules/forks.md
@@ -2,20 +2,6 @@
 
 Forking functionality.
 
-```solidity
-import { Test, forks, Fork } from "vulcan/test.sol";
+{{#include ../examples/forks/example.md}}
 
-contract TestMyContract is Test {
-    function testMyContract() external {
-        // Alternatively an endpoint can be passed directly.
-        Fork fork = forks.create("mainnet");
-
-        // The fork can be created at an specific block
-        fork = forks.createAtBlock("mainnet", 16736036);
-
-        // Or right before a transaction
-        fork = forks.createBeforeTx("mainnet", 0x9cad524afce3fcd2e84b8ac30c57ba085fcae053e9bf3ee449cd36d511c10f43);
-    }
-}
-```
 [**Forks API reference**](../references/Forks.md)
diff --git a/test/examples/forks/ForksExample01.t.sol b/test/examples/forks/ForksExample01.t.sol
new file mode 100644
index 00000000..4b9b85da
--- /dev/null
+++ b/test/examples/forks/ForksExample01.t.sol
@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, vulcan} from "vulcan/test.sol";
+import {forks, Fork} from "vulcan/test/Forks.sol";
+import {ctx} from "vulcan/test/Context.sol";
+
+/// @title How to use forks
+/// @dev How to use forks. This example assumes there is a JSON RPC server running at `localhost:8545`
+contract ForksExample is Test {
+    string constant RPC_URL = "http://localhost:8545";
+
+    function test() external {
+        forks.create(RPC_URL).select();
+
+        expect(block.chainid).toEqual(31337);
+    }
+}