New guides

guides/project-environments.mdx

@@ -0,0 +1,136 @@
+---
+title: Projects or environments?
+description: "Best practices for using Octomind"
+icon: "diagram-project"
+---
+
+Based on our usage data, the difference between `Environments` and `Projects` is sometimes not well understood. We will clarify the difference between the concepts and provide guidance on when and how to use each effectively.
+
+## Projects
+
+When you sign up for Octomind, you automatically create your first project during the onboarding process. A project serves as a foundational unit with the following attributes:
+
+- **Name:** You can change the project name at any time.
+- **URL:** This is fixed and cannot be changed after creation. The URL acts as the reference point for all agent interactions, such as test discovery, test proposals, and auto-maintenance. Think of it as the core reference system for our AI agent.
+
+When you create a project, a default environment is automatically set up for you:
+
+<Frame caption="New Octomind project created, 12/2024">
+  <img
+    src="/images/guides/project-settings.png"
+    alt="New Octomind project created"
+    width={400}
+  />
+</Frame>
+
+<div class="mt-8" />
+
+<Frame caption="Default environment for a new project, 12/2024">
+  <img
+    src="/images/guides/project-environment.png"
+    alt="Default enviroment for a newproject created"
+    width={400}
+  />
+</Frame>
+
+Additionally, test runs accept a URL as a target for executing tests. This feature is particularly useful if you want to test against a specific branch.
+
+<note>
+  In our example, where only one environment is configured, the target URL must
+  match the same test user credentials and security settings as the default
+  environment.
+</note>
+
+<Frame caption="Running tests against a selected URL, 12/2024">
+  <img
+    src="/images/guides/run-against-url.png"
+    alt="Running tests against a selected UR"
+    width={400}
+  />
+</Frame>
+
+## Environments
+
+Environments exist within projects and represent different configurations for the same app under test. Each environment is defined by:
+
+- **Name** and **URL**
+- **Login parameters** (e.g., test user credentials)
+- **OTP secrets** (if applicable)
+- **Basic-auth settings** (if applicable)
+
+You can create as many environments as needed, tailoring each to specific deployment configurations.
+
+## Example: Sandbox and Staging environments
+
+Imagine your app is deployed in two distinct environments: `Sandbox` and `Staging`. Each environment has unique characteristics:
+
+1. **Sandbox:**
+
+- Behind basic-auth
+- Uses `[email protected]`
+
+2. **Default environment (Staging):**
+
+- No basic-auth
+- Uses `[email protected]`
+- Considered to be more stable and primarily used for QA before production deployment
+
+Here's how you'd configure Octomind for this setup:
+
+### 1. Project setup
+
+- Create a project using the `Staging` environment as the reference system.
+- During setup, provide the `Staging URL` and `testuser-staging` credentials.
+- Compose test cases based on the `Staging` environment.
+
+### 2. Adding Sandbox environment
+
+- Set up a new environment for `Sandbox`, specifying its unique URL, user credentials, and authentication settings.
+
+<Frame caption="Setting up a new enviroment for the Sandbox example, 12/2024">
+  <img
+    src="/images/guides/sandbox-environment.png"
+    alt="Set up of a new sandbox environment"
+    width={400}
+  />
+</Frame>
+
+Once configured, you can run all tests against the `Sandbox` environment by selecting it from the `environment drop-down menu` or by providing the **“environment name” parameter** in your pipeline. Please, see our [GitHub documentation](https://octomind.dev/docs/integrations/quickstart-GitHub#5-include-the-github-action) for the CI pipeline details.
+
+<Frame caption="Environment dropdown menu for the example, 12/2024">
+  <img
+    src="/images/guides/environment-dropdown.png"
+    alt="Environment dropdown menu for the example"
+    width={400}
+  />
+</Frame>
+
+## When to use multiple projects
+
+There are cases where multiple projects are more suitable than multiple environments within a single project. Here are two common scenarios:
+
+### A: Testing multiple apps
+
+Each app you test should have its own dedicated project. This keeps configurations and test cases separate, ensuring clarity and manageability.
+
+### B: Testing complex apps with distinct user roles
+
+For apps with users of significantly different roles and permissions, splitting tests across multiple projects can simplify testing. Let's look at two examples:
+
+#### Example 1: Online meeting app
+
+Your app includes two key roles:
+
+- **Meeting Host:** The paying customer who organizes meetings.
+- **Attendee:** A participant who typically doesn't have an account.
+
+Since the test cases for these roles are vastly different, it's best to create a separate project for each role.
+
+#### Example 2: Document signing app
+
+In this app, there are two main roles:
+
+- **User:** The paying customer who uploads documents, prepares them for signing, and shares them with participants.
+- **Participant:** A non-account user who can only sign documents with limited functionality.
+
+Here, too, splitting roles into different projects allows for cleaner, more focused test case management.

integrations-overview.mdx → integrations/integrations-overview.mdx

@@ -19,10 +19,12 @@ We'll happily take over and maintain them further.
 
 <CardGroup cols={2}>
 
-    <Card title="GitHub" icon="github" href="integrations/quickstart-GitHub">
+    <Card title="GitHub" icon="github" href="/integrations/quickstart-GitHub">
+    Integrate with your GitHub repo
     </Card>
 
-    <Card title="Azure DevOps" icon="microsoft" iconType="solid" href="integrations/quickstart-Azure">
+    <Card title="Azure DevOps" icon="microsoft" iconType="solid" href="/integrations/quickstart-Azure">
+    Integrate with your Azure DevOps
     </Card>
 
 </CardGroup>
@@ -34,12 +36,15 @@ We'll happily take over and maintain them further.
 <CardGroup cols={2}>
 
     <Card title="Vercel CI" icon="triangle" iconType="sharp-solid" href="integrations/quickstart-Vercel">
+    Integrate with Vercel
     </Card>
 
     <Card title="Jenkins" icon="jenkins" iconType="solid" href="integrations/quickstart-Jenkins">
+    Integrate with Jenkins
     </Card>
 
     <Card title="Other" icon="person-digging" iconType="solid" href="integrations/quickstart-Other">
+    Integrate with other CI pipelines
     </Card>
 
 </CardGroup>

integrations/quickstart-Other.mdx

@@ -6,6 +6,6 @@ icon: "person-digging"
 
 ## Using the REST endpoint
 
-For other platforms like bitbucket or gitlab you can consult [the documentation for triggering a report via the REST endpoint](../execution-without-ci).
+For other platforms like bitbucket or gitlab you can consult [the documentation for triggering a report via the REST endpoint](/get-started/execution-without-ci).
 
 If you use another system and would like a more seamless experience please let us know!

mint.json

@@ -15,6 +15,7 @@
   "modeToggle": {
     "default": "dark"
   },
+  "layout": "topnav",
   "favicon": "/logo/favicon.svg",
   "colors": {
     "primary": "#00E2AA",
@@ -25,69 +26,68 @@
       "light": "#FFFFFF"
     }
   },
-  "topAnchor": {
-    "name": "Documentation",
-    "icon": "octopus-deploy",
-    "iconType": "solid"
-  },
-  "anchors": [
+  "topbarLinks": [
     {
       "name": "GitHub",
-      "icon": "github",
       "url": "https://github.com/OctoMind-dev"
     },
     {
       "name": "Get easy help",
-      "icon": "discord",
       "url": "https://discord.gg/3ShnZMKRfA"
-    },
-    {
-      "name": "API Reference",
-      "openapi": "/openapi.yaml",
-      "url": "api-reference",
-      "icon": "square-terminal"
-    }
-  ],
-  "topbarLinks": [
-    {
-      "name": "About",
-      "url": "https://www.octomind.dev/about"
     }
   ],
   "topbarCtaButton": {
     "name": "Go to app",
     "url": "https://app.octomind.dev/setup/url?utm_source=docs&utm_medium=txt-lnk"
   },
-  "navigation": [
+  "primaryTab": {
+    "name": "Documentation"
+  },
+  "tabs": [
     {
-      "group": "Get Started",
-      "pages": ["first-steps"]
+      "name": "Guides",
+      "url": "guides"
     },
     {
-      "group": "Expand Your Test Suite",
-      "pages": [
-        "generate-more-test-cases",
-        "new-test-case",
-        "test-case-creation-strategy"
-      ]
+      "name": "API Reference",
+      "url": "api-reference",
+      "openapi": "/openapi.yaml"
     },
     {
-      "group": "Execute Your Tests",
+      "name": "Integrations",
+      "url": "integrations"
+    },
+    {
+      "name": "Changelog",
+      "url": "changelog"
+    }
+  ],
+  "navigation": [
+    {
+      "group": "Get started",
       "pages": [
-        "execute-test-cases",
-        "debugtopus",
-        "scheduled-execution",
-        "integrations-overview",
-        "execution-without-ci"
+        "get-started/first-steps",
+        "get-started/generate-more-test-cases",
+        "get-started/new-test-case",
+        "get-started/edit-test-case",
+        "get-started/execute-test-cases",
+        "get-started/scheduled-execution",
+        "get-started/execution-without-ci",
+        "get-started/debugtopus"
       ]
     },
+    {
+      "group": "Changelog",
+      "pages": ["changelog/changelog"]
+    },
     {
       "group": "Maintain Your Tests",
-      "pages": ["edit-test-case", "maintain-tests", "mark-tests-as-active"]
+      "pages": ["maintain/maintain-tests", "maintain/mark-tests-as-active"]
     },
     {
-      "group": "CI integrations",
+      "group": "Integrations",
       "pages": [
+        "integrations/integrations-overview",
         "integrations/quickstart-GitHub",
         "integrations/quickstart-Azure",
         "integrations/quickstart-Vercel",
@@ -96,10 +96,21 @@
       ]
     },
     {
-      "group": "Account & Views",
+      "group": "Guides",
+      "pages": [
+        "guides/test-creation-best-practices",
+        "guides/test-debugging-1",
+        "guides/test-debugging-2",
+        "guides/test-debugging-3",
+        "guides/test-debugging-4"
+      ]
+    },
+    {
+      "group": "Account & views",
       "pages": [
         "account-view/account",
         "account-view/projects",
+        "account-view/environments",
         "account-view/test-cases",
         "account-view/test-reports"
       ]
@@ -108,7 +119,6 @@
       "group": "Advanced",
       "pages": [
         "advanced/variables",
-        "advanced/environments",
         "advanced/rate-limiting",
         "proxy/private-location",
         "proxy/proxy-settings",
@@ -119,19 +129,15 @@
       ]
     },
     {
-      "group": "Changelog",
-      "pages": ["changelog"]
-    },
-    {
-      "group": "More Info",
+      "group": "More info",
       "pages": [
         "more-info/faq",
         "more-info/octo-dictionary",
         "more-info/under-the-hood"
       ]
     },
     {
-      "group": "Data Governance",
+      "group": "Data governance",
       "pages": ["data-governance/no-code-access", "data-governance/nda"]
     }
   ],

package.json

@@ -13,5 +13,8 @@
     "mintlify": "^4.0.289",
     "prettier": "^3.4.2"
   },
-  "packageManager": "[email protected]+sha512.22721b3a11f81661ae1ec68ce1a7b879425a1ca5b991c975b074ac220b187ce56c708fe5db69f4c962c989452eee76c82877f4ee80f474cebd61ee13461b6228"
+  "packageManager": "[email protected]+sha512.22721b3a11f81661ae1ec68ce1a7b879425a1ca5b991c975b074ac220b187ce56c708fe5db69f4c962c989452eee76c82877f4ee80f474cebd61ee13461b6228",
+  "dependencies": {
+    "sharp": "^0.33.5"
+  }
 }