GITBOOK-23: Updating based on changes to framework that simplify the GUI api

Author: lipmaneth

SUMMARY.md

@@ -6,7 +6,7 @@
 
 ## Platform
 
-* [GuardianTest](platform/guardian-test/GuardianTest.md)
+* [GuardianTest](platform/readme/GuardianTest.md)
   * [Overview](platform/guardian-test/overview/README.md)
     * [Key Benefits](platform/guardian-test/overview/key-benefits.md)
     * [Framework Roadmap](platform/guardian-test/overview/framework-roadmap.md)
@@ -34,7 +34,7 @@
     * [Check Results](platform/continuous-monitoring/monitoring/check-results.md)
     * [How We Store Data](platform/continuous-monitoring/monitoring/how-we-store-data.md)
   * [Browser Checks](platform/continuous-monitoring/browser-checks/README.md)
-    * [Writing Tests](platform/guardian-test/getting-started/writing-your-first-e2e-test.md)
+    *
     * [Request Custom Test Writing](platform/continuous-monitoring/browser-checks/request-custom-test-writing.md)
     * [Submitting Tests for Monitoring](platform/continuous-monitoring/browser-checks/submitting-tests-for-monitoring.md)
   * [Alerts](platform/continuous-monitoring/alerts/README.md)

platform/guardian-test/api/gui.md

@@ -24,39 +24,6 @@ await gui.initializeChain(1, 17110784)
 
 
 
-### killChain
-
-Kills any existing forked networks. Should be used at the end of a test to make sure there are no collisions with tests spawning networks.
-
-#### **Inputs**
-
-* None
-
-#### **Usage**
-
-```javascript
-await gui.killChain()
-```
-
-
-
-### initializeWallet
-
-Updates the wallet provider in the injected wallet to use a specific chain ID.
-
-#### **Inputs**
-
-* `chainId` - The desired network chain ID to update the wallet provider
-
-#### **Usage**
-
-```javascript
-// Updates the wallet provider to connect to Arbitrum
-await gui.initializeWallet(42161);
-```
-
-
-
 ### setAllowance
 
 Sets the allowance of an address to spend the test wallet's ERC20 tokens to a specific amount.

platform/guardian-test/getting-started/installation.md

@@ -41,7 +41,11 @@ You can install GuardianTest using either npm or yarn:
 
 At your repo's top-level directory create a file called `playwright.config.ts`.
 
-If you already are using Playwright and already have a `playwright.config.ts`, just add `/.*gui\.(js|ts|mjs)/` to the `testMatch` entry to make sure Playwright recognizes our tests.
+If you already are using Playwright and already have a `playwright.config.ts:`
+
+* Add `/.*gui\.(js|ts|mjs)/` to the `testMatch` entry to make sure Playwright recognizes our tests
+* Set `fullyParallel` to `false`
+* Set `workers` to `1`
 
 ```typescript
 import { devices, PlaywrightTestConfig } from '@playwright/test';

platform/guardian-test/getting-started/writing-your-first-e2e-test.md

@@ -20,10 +20,10 @@ await page.goto("https://guardianui.com");
 
 #### Interaction
 
-Performing interactions involves two pieces. 
+Performing interactions involves two pieces.
 
 * The locator of the object to interact with (for more information, check out the [Playwright Locators API documentation](https://playwright.dev/docs/locators)).
-* The action to take. 
+* The action to take.
 
 By default Playwright waits for an element to be actionable before attempting to perform an action.
 
@@ -46,8 +46,6 @@ Playwright has a robust suite of actions built into the Locator API, the most co
 | `locator.press()`        | Press a single key                              |
 | `locator.selectOption()` | Select on option from a drop down               |
 
-
-
 ### Making General Assertions
 
 Playwright natively includes test assertions by way of an `expect` function. For more information on the available functionality of `expect`, check out the [Playwright Assertions documentation](https://playwright.dev/docs/test-assertions).
@@ -74,8 +72,6 @@ There are also many async assertions which wait until the expected condition is
 | `expect(page).toHaveTitle()`        | Assert that the page has a certain title             |
 | `expect(page).toHaveURL()`          | Assert that the page has a certain URL               |
 
-
-
 ### Using Hooks
 
 You can use test hooks to define groups of tests, or hooks like `test.beforeAll`, `test.beforeEach`, `test.afterAll`, and `test.afterEach` to perform reused sets of actions before/after each test or as setup/teardown for test suites. For more information visit the [Playwright Test Hooks documentation](https://playwright.dev/docs/api/class-test).
@@ -92,15 +88,12 @@ test.describe("hooks example", () => {
     });
 
     test.afterEach(async ({ page, gui }) => {
-        // Tear down Arbitrum fork after each test
-        await gui.killChain();
+        // Do something after each test
     });
 
     test("example test", async ({ page, gui }) => {
         await page.goto("https://guardianui.com");
 
-        await gui.initializeWallet(1);
-        
         // Set ETH balance to 1 for the test wallet
         await gui.setEthBalance("1000000000000000000");
 
@@ -115,26 +108,20 @@ test.describe("hooks example", () => {
 });ypoe
 ```
 
-
-
 ## Writing a GuardianTest Test
 
 There are eight phases to writing your first GuardianUI end-to-end test:
 
 1. Forked network initialization
 2. Navigation to the dApp
-3. Wallet initialization
-4. Wallet state mocking
-5. Wallet connection
-6. Performing actions within the dApp
-7. Transaction submission and verification
-8. Stop the forked network
-
-
+3. Wallet state mocking
+4. Wallet connection
+5. Performing actions within the dApp
+6. Transaction submission and verification
 
 ### Phase 1: Forked Network Initialization
 
-In order to set network state and perform network interactions without expending real tokens, every test that plans to interact with a live network needs to begin by initializing a forked network.
+In order to set network state and perform network interactions without expending real tokens, every test that plans to interact with a live network needs to begin by initializing a forked network. Within this call you can specify the network you wish to fork using its chain ID, and optionally what block number you want to fork at (if you don't specify a block it runs at the latest). We recommend pinning to a block as it increases deterministicness of the tests.
 
 <pre class="language-typescript"><code class="lang-typescript">import { test } from "@guardianui/test";
 
@@ -148,7 +135,7 @@ test.describe("Olympus Example Suite", () => {
 });
 </code></pre>
 
-
+###
 
 ### Phase 2: Navigation To The dApp
 
@@ -169,33 +156,9 @@ test.describe("Olympus Example Suite", () => {
 });
 </code></pre>
 
+###
 
-
-### Phase 3: Wallet Initialization
-
-In order for the test to behave correctly and consistently, you will need to initialize the injected wallet with the chain ID of the network it should be connected to.
-
-<pre class="language-typescript"><code class="lang-typescript">import { test } from "@guardianui/test";
-
-test.describe("Olympus Example Suite", () => {
-    test("Should stake OHM to gOHM", async ({ page, gui }) => {
-        // Initialize a fork of Ethereum mainnet (chain ID 1)
-        await gui.initializeChain(1);
-        
-        // Navigate to the Olympus dApp
-        await page.goto("https://app.olympusdao.finance/#/stake");
-        
-<strong>        // Initialize wallet to connect to Ethereum mainnet (chain ID 1)
-</strong><strong>        await gui.initializeWallet(1);
-</strong>        
-        // Complete the rest of the test
-    });
-});
-</code></pre>
-
-
-
-### Phase 4: Wallet State Mocking
+### Phase 3: Wallet State Mocking
 
 The test wallet injected into the browser during these tests is empty by default. We can provide it with gas tokens, ERC20 tokens, and set allowances in a few quick lines.
 
@@ -209,9 +172,6 @@ test.describe("Olympus Example Suite", () => {
         // Navigate to the Olympus dApp
         await page.goto("https://app.olympusdao.finance/#/stake");
 
-        // Initialize wallet to connect to Ethereum mainnet (chain ID 1)
-        await gui.initializeWallet(1);
-        
 <strong>        // Set ETH balance
 </strong><strong>        await gui.setEthBalance("100000000000000000000000");
 </strong><strong>        
@@ -226,13 +186,13 @@ test.describe("Olympus Example Suite", () => {
 });
 </code></pre>
 
+###
 
-
-### Phase 5: Wallet Connection
+### Phase 4: Wallet Connection
 
 The wallet connection flow will vary slightly from dApp to dApp, but usually requires locating a **"Connect Wallet"** button, and then selecting the **"Metamask"** option in an ensuing modal. While our wallet is not actually Metamask, it is surfaced to apps in a way that looks like Metamask to avoid issues where sites may not have an option to select an injected wallet.
 
-To get a sense of what to write in the test, manually go to your live application and identify the visual and textual elements you need to click to go from the not-connected state to the connected state. Use the "inspect element" tool in browsers to help with this.&#x20;
+To get a sense of what to write in the test, manually go to your live application and identify the visual and textual elements you need to click to go from the not-connected state to the connected state. Use the "inspect element" tool in browsers to help with this.
 
 See examples in our [test examples](https://app.gitbook.com/o/aEzOvP1ODgbzLwqZ2irE/s/6blK04TyOYOkA5ZEQW4b/end-to-end-testing/test-examples) section.
 
@@ -246,9 +206,6 @@ test.describe("Olympus Example Suite", () => {
         // Navigate to the Olympus dApp
         await page.goto("https://app.olympusdao.finance/#/stake");
 
-        // Initialize wallet to connect to Ethereum mainnet (chain ID 1)
-        await gui.initializeWallet(1);
-        
         // Set ETH balance
         await gui.setEthBalance("100000000000000000000000");
 
@@ -274,9 +231,9 @@ test.describe("Olympus Example Suite", () => {
 });
 </code></pre>
 
+###
 
-
-### Phase 6: Performing Actions Within the dApp
+### Phase 5: Performing Actions Within the dApp
 
 This will vary drastically from dApp to dApp, but generally requires identifying elements on the web page based on class or ID selectors and clicking or entering information into them.
 
@@ -292,9 +249,6 @@ test.describe("Olympus Example Suite", () => {
         // Navigate to the Olympus dApp
         await page.goto("https://app.olympusdao.finance/#/stake");
 
-        // Initialize wallet to connect to Ethereum mainnet (chain ID 1)
-        await gui.initializeWallet(1);
-        
         // Set ETH balance
         await gui.setEthBalance("100000000000000000000000");
 
@@ -319,12 +273,12 @@ test.describe("Olympus Example Suite", () => {
 <strong>        // Performing actions within the dApp
 </strong><strong>        // Enter OHM input amount
 </strong><strong>        await page.locator("[data-testid='ohm-input']").type("0.1");
-</strong><strong>
-</strong><strong>        // Click the stake button to open the modals
+</strong>
+<strong>        // Click the stake button to open the modals
 </strong><strong>        await page.waitForSelector("[data-testid='submit-button']");
 </strong><strong>        await page.locator("[data-testid='submit-button']").click();
-</strong><strong>
-</strong><strong>        // Click the pre-transaction checkbox
+</strong>
+<strong>        // Click the pre-transaction checkbox
 </strong><strong>        await page.waitForSelector("[class='PrivateSwitchBase-input css-1m9pwf3']");
 </strong><strong>        await page.locator("[class='PrivateSwitchBase-input css-1m9pwf3']").click();
 </strong>        
@@ -333,9 +287,9 @@ test.describe("Olympus Example Suite", () => {
 });
 </code></pre>
 
+###
 
-
-### Phase 7: Transaction Submission and Verification
+### Phase 6: Transaction Submission and Verification
 
 One of the primary novel behaviors of the GuardianTest framework is its ability to validate information around network transactions following a site interaction such as a button click. Doing this requires two pieces of information:
 
@@ -354,9 +308,6 @@ test.describe("Olympus Example Suite", () => {
         // Navigate to the Olympus dApp
         await page.goto("https://app.olympusdao.finance/#/stake");
 
-        // Initialize wallet to connect to Ethereum mainnet (chain ID 1)
-        await gui.initializeWallet(1);
-        
         // Set ETH balance
         await gui.setEthBalance("100000000000000000000000");
 
@@ -391,68 +342,6 @@ test.describe("Olympus Example Suite", () => {
 
 <strong>        // Submit stake transaction
 </strong><strong>        await gui.validateContractInteraction("[data-testid='submit-modal-button']", "0xb63cac384247597756545b500253ff8e607a8020");
-</strong>        
-        // Complete the rest of the test
-    });
-});
-</code></pre>
-
-
-
-### Phase 8: Stop The Forked Network
-
-GuardianUI tests run in sequence to avoid port collisions when creating and using Anvil forks. However, the fork isn't torn down at the end of a test by default, so to end the test you need to specify that the fork is no longer needed.
-
-<pre class="language-typescript"><code class="lang-typescript">import { test } from "@guardianui/test";
-
-test.describe("Olympus Example Suite", () => {
-    test("Should stake OHM to gOHM", async ({ page, gui }) => {
-        // Initialize a fork of Ethereum mainnet (chain ID 1)
-        await gui.initializeChain(1);
-        
-        // Navigate to the Olympus dApp
-        await page.goto("https://app.olympusdao.finance/#/stake");
-        
-        // Initialize wallet to connect to Ethereum mainnet (chain ID 1)
-        await gui.initializeWallet(1);
-        
-        // Set ETH balance
-        await gui.setEthBalance("100000000000000000000000");
-        
-        // Set OHM balance
-        await gui.setAllowance("0x64aa3364f17a4d01c6f1751fd97c2bd3d7e7f1d5", "0xb63cac384247597756545b500253ff8e607a8020", "1000000000000000000000000");
-        
-        // Set staking contract's approval to spend OHM
-        await gui.setBalance("0x64aa3364f17a4d01c6f1751fd97c2bd3d7e7f1d5", "1000000000000000000000000");
-        
-        // Connect wallet
-        await page.waitForSelector("text=Connect Wallet");
-        await page.locator("text=Connect Wallet").first().click();
-        await page.waitForSelector("text=Connect Wallet");
-        await page.locator("text=Connect Wallet").first().click();
-        await page.locator("text=Metamask").first().click();
-        
-        // This is specific to Olympus. A side tab is opened upon wallet connection
-        // so we click out of it
-        await page.locator("[id='root']").click({ position: {x: 0, y: 0}, force: true });
-        
-        // Performing actions within the dApp
-        // Enter OHM input amount
-        await page.locator("[data-testid='ohm-input']").type("0.1");
-
-        // Click the stake button to open the modals
-        await page.waitForSelector("[data-testid='submit-button']");
-        await page.locator("[data-testid='submit-button']").click();
-
-        // Click the pre-transaction checkbox
-        await page.waitForSelector("[class='PrivateSwitchBase-input css-1m9pwf3']");
-        await page.locator("[class='PrivateSwitchBase-input css-1m9pwf3']").click();
-        
-        // Submit stake transaction
-        await gui.validateContractInteraction("[data-testid='submit-modal-button']", "0xb63cac384247597756545b500253ff8e607a8020");
-        
-        // Stop the forked network
-<strong>        await gui.killChain();
 </strong>    });
 });
 </code></pre>

platform/guardian-test/overview/supported-chains.md

@@ -6,3 +6,5 @@ GuardianTest currently supports four popular EVM chains:
 * Arbitrum
 * Optimism
 * Polygon PoS
+
+NOTE: The framework is most thoroughly tested on Ethereum, you are more likely to bump into issues on other chains

platform/readme/GuardianTest.md

@@ -0,0 +1,20 @@
+---
+description: >-
+  Meet the new standard for web3 end-to-end testing. Reliably test in a
+  production-like environment across any EVM-compatible chain using our open
+  source framework.
+---
+
+# GuardianTest
+
+GuardianTest is an open source E2E testing framework developed to suit the demands of crypto organizations and developers.
+
+It extends the popular [Playwright](https://playwright.dev/) testing framework so developers can easily:
+
+* Engage with local deployments, staging deployments, OR live production
+* Perform tests on EVM compatible chains
+* Pin tests to any block
+* Interact with a site using a wallet
+* Mock ERC20 balances and allowances
+* Validate target contract addresses from app interactions
+* Perform any other actions or validation Playwright offers