chore: update examples and autogenerate docs (#241)

* chore: update examples and autogenerate docs

* fix: fe test

* fix: fe test

docs/src/examples/commands/example.md

@@ -11,14 +11,11 @@ import {Test, expect, commands, CommandResult, CommandOutput} from "vulcan/test.
 
 contract RunCommandExample is Test {
     function test() external {
-        // Run a command to get a result
-        CommandResult cmdResult = commands.run(["echo", "Hello, World!"]);
-
-        // Obtain the output from the result
-        CommandOutput memory output = cmdResult.expect("Failed to run command");
+        // Run the command
+        CommandOutput memory result = commands.run(["echo", "Hello, World!"]).unwrap();
 
         // Check the output
-        expect(string(output.stdout)).toEqual("Hello, World!");
+        expect(string(result.stdout)).toEqual("Hello, World!");
     }
 }
 
@@ -39,13 +36,9 @@ contract ReuseACommandExample is Test {
         // Create a command
         Command memory echo = commands.create("echo");
 
-        // Run the commands and get the results
-        CommandResult fooResult = echo.arg("foo").run();
-        CommandResult barResult = echo.arg("bar").run();
-
-        // Obtain the outputs from the results
-        CommandOutput memory fooOutput = fooResult.expect("Failed to run echo 'foo'");
-        CommandOutput memory barOutput = barResult.expect("Failed to run echo 'bar'");
+        // Run the commands and unwrap the results
+        CommandOutput memory fooOutput = echo.arg("foo").run().unwrap();
+        CommandOutput memory barOutput = echo.arg("bar").run().unwrap();
 
         // Check the outputs
         expect(string(fooOutput.stdout)).toEqual("foo");

docs/src/examples/expect/example.md

@@ -7,24 +7,26 @@ Using the `expect` function and its different matchers
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
 
-import {Test, expect} from "vulcan/test.sol";
+import {Test, accounts, expect} from "vulcan/test.sol";
 
 contract ExpectExample is Test {
     function test() external {
-        expect(string("foo")).toEqual(string("foo"));
-        expect(string("foo")).not.toEqual(string("bar"));
-        expect(string("foo bar")).toContain(string("foo"));
-        expect(string("foo bar")).toContain(string("bar"));
-
-        expect(uint256(1)).toEqual(uint256(1));
-        expect(uint256(1)).not.toEqual(uint256(0));
-        expect(uint256(1)).toBeGreaterThan(uint256(0));
-        expect(uint256(1)).toBeGreaterThanOrEqual(uint256(1));
-        expect(uint256(0)).toBeLessThan(uint256(1));
-        expect(uint256(0)).toBeLessThanOrEqual(uint256(0));
-
-        expect(address(1)).toEqual(address(1));
-        expect(address(1)).not.toEqual(address(0));
+        expect(string("foo")).toEqual("foo");
+        expect(string("foo")).not.toEqual("bar");
+        expect(string("foo bar")).toContain("foo");
+        expect(string("foo bar")).toContain("bar");
+
+        expect(uint256(1)).toEqual(1);
+        expect(uint256(1)).not.toEqual(0);
+        expect(uint256(1)).toBeGreaterThan(0);
+        expect(uint256(1)).toBeGreaterThanOrEqual(1);
+        expect(uint256(0)).toBeLessThan(1);
+        expect(uint256(0)).toBeLessThanOrEqual(0);
+
+        address alice = accounts.create("Alice");
+        address bob = accounts.create("Bob");
+        expect(alice).toEqual(alice);
+        expect(alice).not.toEqual(bob);
 
         expect(true).toBeTrue();
         expect(false).toBeFalse();

docs/src/examples/fe/example.md

@@ -13,11 +13,12 @@ contract FeExample is Test {
     function test() external {
         Fe memory feCmd = fe.create().setFilePath("./test/mocks/guest_book.fe").setOverwrite(true);
 
+        // Compile the bytecode and revert if there is an error
         feCmd.build().unwrap();
 
-        string memory expectedBytecode = "600180600c6000396000f3fe00";
+        bytes memory bytecode = feCmd.getBytecode("MyFeContract").toValue();
 
-        expect(string(feCmd.getBytecode("A").toValue())).toEqual(expectedBytecode);
+        expect(bytecode).toEqual("600180600c6000396000f3fe00");
     }
 }
 

docs/src/examples/format/example.md

@@ -7,7 +7,7 @@ Using templates with the `format` module to format data
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
 
-import {Test, accounts, expect, fmt} from "vulcan/test.sol";
+import {Test, accounts, expect, fmt, println} from "vulcan/test.sol";
 
 contract FormatExample is Test {
     using accounts for address;
@@ -16,9 +16,15 @@ contract FormatExample is Test {
         address target = address(1).setBalance(1);
         uint256 balance = target.balance;
 
-        expect(fmt.format("The account {address} has {uint} wei", abi.encode(target, balance))).toEqual(
-            "The account 0x0000000000000000000000000000000000000001 has 1 wei"
-        );
+        // Store it as a string
+        // NOTE: The {address} and {uint} placeholders can be abbreviated as {a} and {u}
+        // For available placeholders and abbreviations see: TODO
+        string memory result = fmt.format("The account {address} has {uint} wei", abi.encode(target, balance));
+
+        expect(result).toEqual("The account 0x0000000000000000000000000000000000000001 has 1 wei");
+
+        // Format is also used internally by Vulcan's println, which you can use as an alternative to console.log
+        println("The account {address} has {uint} wei", abi.encode(target, balance));
     }
 }
 
@@ -41,9 +47,10 @@ contract FormatExample is Test {
         address target = address(1).setBalance(1e17);
         uint256 balance = target.balance;
 
-        expect(fmt.format("The account {address} has {uint:d18} eth", abi.encode(target, balance))).toEqual(
-            "The account 0x0000000000000000000000000000000000000001 has 0.1 eth"
-        );
+        // Store it as a string
+        string memory result = fmt.format("The account {address} has {uint:d18} eth", abi.encode(target, balance));
+
+        expect(result).toEqual("The account 0x0000000000000000000000000000000000000001 has 0.1 eth");
     }
 }
 

docs/src/examples/fs/example.md

@@ -16,14 +16,11 @@ contract FsExample is Test {
     string constant BINARY_TEST_FILE = "./test/fixtures/fs/write/test_binary.txt";
 
     function test() external {
-        StringResult stringResult = fs.readFile(HELLO_WORLD);
-        BytesResult bytesResult = fs.readFileBinary(HELLO_WORLD);
+        string memory stringResult = fs.readFile(HELLO_WORLD).unwrap();
+        expect(stringResult).toEqual("Hello, World!\n");
 
-        expect(stringResult.isOk()).toBeTrue();
-        expect(bytesResult.isOk()).toBeTrue();
-
-        expect(stringResult.unwrap()).toEqual("Hello, World!\n");
-        expect(bytesResult.toValue()).toEqual(bytes("Hello, World!\n"));
+        bytes memory bytesResult = fs.readFileBinary(HELLO_WORLD).unwrap();
+        expect(bytesResult).toEqual("Hello, World!\n");
     }
 }
 
@@ -45,21 +42,19 @@ contract FsExample is Test {
     string constant TEXT_TEST_FILE = "./test/fixtures/fs/write/example.txt";
 
     function test() external {
-        EmptyResult writeStringResult = fs.writeFile(TEXT_TEST_FILE, "This is a test");
-
-        expect(writeStringResult.isOk()).toBeTrue();
-
-        StringResult readStringResult = fs.readFile(TEXT_TEST_FILE);
+        // Write string
+        fs.writeFile(TEXT_TEST_FILE, "This is a test").expect("Failed to write file");
 
-        expect(readStringResult.unwrap()).toEqual("This is a test");
+        string memory readStringResult = fs.readFile(TEXT_TEST_FILE).unwrap();
 
-        EmptyResult writeBytesResult = fs.writeFileBinary(TEXT_TEST_FILE, bytes("This is a test in binary"));
+        expect(readStringResult).toEqual("This is a test");
 
-        expect(writeBytesResult.isOk()).toBeTrue();
+        // Write binary
+        fs.writeFileBinary(TEXT_TEST_FILE, "This is a test in binary").expect("Failed to write file");
 
-        BytesResult readBytesResult = fs.readFileBinary(TEXT_TEST_FILE);
+        bytes memory readBytesResult = fs.readFileBinary(TEXT_TEST_FILE).unwrap();
 
-        expect(readBytesResult.unwrap()).toEqual(bytes("This is a test in binary"));
+        expect(readBytesResult).toEqual("This is a test in binary");
     }
 }
 
@@ -75,7 +70,7 @@ pragma solidity ^0.8.13;
 
 import {Test} from "vulcan/test.sol";
 import {expect} from "vulcan/test/Expect.sol";
-import {fs, FsMetadataResult} from "vulcan/test/Fs.sol";
+import {fs, FsMetadata} from "vulcan/test/Fs.sol";
 import {BoolResult} from "vulcan/test/Result.sol";
 
 contract FsExample is Test {
@@ -85,17 +80,14 @@ contract FsExample is Test {
     string constant NOT_FOUND_EXAMPLE = "./test/fixtures/fs/read/lkjjsadflkjasdf.txt";
 
     function test() external {
-        FsMetadataResult metadataResult = fs.metadata(READ_EXAMPLE);
-        expect(metadataResult.isOk()).toBeTrue();
-        expect(metadataResult.unwrap().isDir).toBeFalse();
+        FsMetadata memory metadata = fs.metadata(READ_EXAMPLE).expect("Failed to get metadata");
+        expect(metadata.isDir).toBeFalse();
 
-        BoolResult existsResult = fs.fileExists(READ_EXAMPLE);
-        expect(existsResult.isOk()).toBeTrue();
-        expect(existsResult.unwrap()).toBeTrue();
+        bool exists = fs.fileExists(READ_EXAMPLE).unwrap();
+        expect(exists).toBeTrue();
 
-        BoolResult notFoundResult = fs.fileExists(NOT_FOUND_EXAMPLE);
-        expect(notFoundResult.isOk()).toBeTrue();
-        expect(notFoundResult.unwrap()).toBeFalse();
+        exists = fs.fileExists(NOT_FOUND_EXAMPLE).unwrap();
+        expect(exists).toBeFalse();
     }
 }
 

docs/src/examples/huff/example.md

@@ -7,12 +7,12 @@ How to compile `huff` code using the `huff` module (Requires to have `huff` inst
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
 
-import {Test, expect, huff, CommandResult} from "vulcan/test.sol";
+import {Test, expect, huff, CommandOutput} from "vulcan/test.sol";
 
 contract HuffExample is Test {
     function test() external {
-        CommandResult initcode = huff.create().setFilePath("./test/mocks/Getter.huff").compile();
-        expect(initcode.unwrap().stdout.length).toBeGreaterThan(0);
+        CommandOutput memory result = huff.create().setFilePath("./test/mocks/Getter.huff").compile().unwrap();
+        expect(result.stdout.length).toBeGreaterThan(0);
     }
 }
 

docs/src/examples/requests/example.md

@@ -27,32 +27,6 @@ contract RequestExample is Test {
 
 ```
 
-### Sending a JSON payload
-
-How to send a request with a JSON body
-
-```solidity
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.13;
-
-import {Test, expect, request, Response, RequestClient, JsonObject} from "vulcan/test.sol";
-
-contract RequestExample is Test {
-    function test() external {
-        RequestClient memory client = request.create();
-
-        Response memory jsonRes = client.post("https://httpbin.org/post").json("{ \"foo\": \"bar\" }").send().unwrap();
-
-        expect(jsonRes.status).toEqual(200);
-
-        JsonObject memory responseBody = jsonRes.json().unwrap();
-
-        expect(responseBody.getString(".json.foo")).toEqual("bar");
-    }
-}
-
-```
-
 ### Request authentication
 
 How to use different methods of authentication

docs/src/examples/results/example.md

@@ -16,17 +16,17 @@ contract ResultExample is Test {
         StringResult result = Ok(string("foo"));
 
         // Use unwrap to get the value or revert if the result is an `Error`
-        string memory unwrapValue = result.unwrap();
-        expect(unwrapValue).toEqual("foo");
+        string memory value = result.unwrap();
+        expect(value).toEqual("foo");
 
         // Use expect to get the value or revert with a custom message if
         // the result is an `Error`
-        string memory expectValue = result.expect("Result failed");
-        expect(expectValue).toEqual("foo");
+        value = result.expect("Result failed");
+        expect(value).toEqual("foo");
 
-        // Safely getting the value
+        // Safely handling the result
         if (result.isOk()) {
-            string memory value = result.toValue();
+            value = result.toValue();
             expect(value).toEqual("foo");
         }
     }
@@ -49,12 +49,14 @@ contract ResultExample is Test {
         // Run a non existent command
         CommandResult result = commands.run(["asdf12897u391723"]);
 
-        // Use unwrap to revert with the default error message
         ctx.expectRevert();
+
+        // Use unwrap to revert with the default error message
         result.unwrap();
 
-        // Use expect to revert with a custom error message
         ctx.expectRevert("Command not executed");
+
+        // Use expect to revert with a custom error message
         result.expect("Command not executed");
 
         bool failed = false;

test/examples/commands/CommandExample01.t.sol

@@ -7,13 +7,10 @@ import {Test, expect, commands, CommandResult, CommandOutput} from "vulcan/test.
 /// @dev Run a simple command and obtain the output
 contract RunCommandExample is Test {
     function test() external {
-        // Run a command to get a result
-        CommandResult cmdResult = commands.run(["echo", "Hello, World!"]);
-
-        // Obtain the output from the result
-        CommandOutput memory output = cmdResult.expect("Failed to run command");
+        // Run the command
+        CommandOutput memory result = commands.run(["echo", "Hello, World!"]).unwrap();
 
         // Check the output
-        expect(string(output.stdout)).toEqual("Hello, World!");
+        expect(string(result.stdout)).toEqual("Hello, World!");
     }
 }

test/examples/commands/CommandExample02.t.sol

@@ -10,13 +10,9 @@ contract ReuseACommandExample is Test {
         // Create a command
         Command memory echo = commands.create("echo");
 
-        // Run the commands and get the results
-        CommandResult fooResult = echo.arg("foo").run();
-        CommandResult barResult = echo.arg("bar").run();
-
-        // Obtain the outputs from the results
-        CommandOutput memory fooOutput = fooResult.expect("Failed to run echo 'foo'");
-        CommandOutput memory barOutput = barResult.expect("Failed to run echo 'bar'");
+        // Run the commands and unwrap the results
+        CommandOutput memory fooOutput = echo.arg("foo").run().unwrap();
+        CommandOutput memory barOutput = echo.arg("bar").run().unwrap();
 
         // Check the outputs
         expect(string(fooOutput.stdout)).toEqual("foo");

test/examples/console/ConsoleExample01.t.sol

@@ -5,6 +5,7 @@ import {Test, expect, console} from "vulcan/test.sol";
 
 /// @title Log values
 /// @dev Use the `console` function to log values.
+/// NOTE: Prefer `println` over `console.log` for a more flexible API.
 contract ConsoleExample is Test {
     function test() external pure {
         string memory foo = "foo";

test/examples/expect/ExpectExample01.t.sol

@@ -1,26 +1,28 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
 
-import {Test, expect} from "vulcan/test.sol";
+import {Test, accounts, expect} from "vulcan/test.sol";
 
 /// @title Use different matchers
 /// @dev Using the `expect` function and its different matchers
 contract ExpectExample is Test {
     function test() external {
-        expect(string("foo")).toEqual(string("foo"));
-        expect(string("foo")).not.toEqual(string("bar"));
-        expect(string("foo bar")).toContain(string("foo"));
-        expect(string("foo bar")).toContain(string("bar"));
+        expect(string("foo")).toEqual("foo");
+        expect(string("foo")).not.toEqual("bar");
+        expect(string("foo bar")).toContain("foo");
+        expect(string("foo bar")).toContain("bar");
 
-        expect(uint256(1)).toEqual(uint256(1));
-        expect(uint256(1)).not.toEqual(uint256(0));
-        expect(uint256(1)).toBeGreaterThan(uint256(0));
-        expect(uint256(1)).toBeGreaterThanOrEqual(uint256(1));
-        expect(uint256(0)).toBeLessThan(uint256(1));
-        expect(uint256(0)).toBeLessThanOrEqual(uint256(0));
+        expect(uint256(1)).toEqual(1);
+        expect(uint256(1)).not.toEqual(0);
+        expect(uint256(1)).toBeGreaterThan(0);
+        expect(uint256(1)).toBeGreaterThanOrEqual(1);
+        expect(uint256(0)).toBeLessThan(1);
+        expect(uint256(0)).toBeLessThanOrEqual(0);
 
-        expect(address(1)).toEqual(address(1));
-        expect(address(1)).not.toEqual(address(0));
+        address alice = accounts.create("Alice");
+        address bob = accounts.create("Bob");
+        expect(alice).toEqual(alice);
+        expect(alice).not.toEqual(bob);
 
         expect(true).toBeTrue();
         expect(false).toBeFalse();