Skip to main content

Workspace Setup

While Rumour allows you to execute individual TOML files anywhere from scratch, structuring your testing codebase in a clean, modular fashion is critical for large, enterprise-grade workspaces.

Instead of crafting directories and environment configs manually, Rumour provides built-in, industry-standard setup subcommands to instantly bootstrap and scale your API testing projects.

The Modular Architecture Philosophy​

In a mature Rumour project, we recommend separating global workspace settings from domain-specific test suites. The ideal directory layout looks like this:

my_api_tests/                  # Your workspace root folder
├── workspace.env.toml         # Global environment variables (e.g. base_url)
├── my_api_tests.config.toml   # Global runner defaults
├── my_api_tests.suite.toml    # Main execution suite linking everything
├── .gitignore                 # Excludes local caches (.rumour/) from Git
│
├── auth/                      # Modular collection for Authentication APIs
│   ├── auth.env.toml          # Auth-specific variable overrides
│   ├── auth.config.toml       # Auth-specific runner defaults (timeouts, retries)
│   ├── auth.suite.toml        # Sequential execution suite for Auth
│   └── requests/              # Dedicated folder for Auth API TOML files
│         ├── login.toml
│         └── logout.toml
│
└── users/                     # Modular collection for User Management APIs
    ├── users.env.toml
    ├── users.config.toml
    ├── users.suite.toml
    └── requests/
          ├── create_user.toml
          └── get_user.toml

This structure guarantees complete variable isolation, prevents naming collisions, and enables effortless parallel test runs.

Step 1: Initialize the Workspace Root​

To set up your project boundary, run rumour init inside your target directory:

rumour init sectionForge

Interactive Prompt: Git Setup​

If the directory does not have an active Git repository, Rumour will intelligently prompt you:

Initialize a Git repository in this workspace? [Y/n]

Pressing Yes will automatically run git init on your behalf, establishing a safe VCS boundary.

It will ask for git initialize:

~/workspace/testing/recommended_setup main ❯ rumour init sectionForge

Initialize a Git repository in this workspace? [Y/n]

press Y or n

~/workspace/testing/recommended_setup main ❯ rumour init sectionForge           

  Rumour workspace successfully initialized!
  Location: /home/bugsfounder/workspace/testing/recommended_setup/sectionForge

  Created:
    • workspace.env.toml  (Workspace global variables & root marker)
    • sectionForge.config.toml  (Workspace global runner configuration)
    • sectionForge.suite.toml  (Workspace global ordered sequence suite)
    • .gitignore          (Configured to ignore local caches & reports)

  Next steps to start testing:
    1. Create a modular collection:   rumour new <collection_name>
       (Example: rumour new auth)
    2. Run your new workflow suite:   rumour run <collection_name>/<collection_name>.suite.toml
       (Example: rumour run auth/auth.suite.toml)

(If you are already inside your target directory, simply run rumour init with no arguments.)

Scaffolded Files at the Root:​

  1. workspace.env.toml: The marker file that defines the workspace boundary. All sibling dependency scans terminate here. 
    [variables]
    base_url = "https://httpbin.org"
  2. sectionForge.config.toml: Contains global execution rules. 
    [config]
    # timeout_ms = 5000
    # max_retries = 3
  3. sectionForge.suite.toml: A root-level sequence runner suite that you can use to orchestrate collections together.
  4. .gitignore: Configured to ignore execution cache/reports stored inside .rumour/ from your git history.

Step 2: Scaffold a Modular Collection​

Once your workspace root is initialized, you can scaffold domain-specific testing collections (like auth or users) using:

rumour new auth

Rumour will automatically detect the workspace root, create the collection directory, and generate dynamic config templates named specifically after your collection:

~/workspace/testing/recommended_setup/sectionForge main* ❯ rumour new auth               

  Collection 'auth' successfully created!
  Location: /home/bugsfounder/workspace/testing/recommended_setup/sectionForge/auth

  Scaffolded:
    • auth/auth.env.toml (Domain environment overrides)
    • auth/auth.config.toml (Domain runner configurations)
    • auth/auth.suite.toml (Ordered sequence runner suite)
    • auth/requests/                 (Subfolder for API request TOMLs)
        └── requests/example.toml    (Documented template request)

  To run this collection's test suite:
    $ rumour run auth/auth.suite.toml

1. Collection-Level Overrides (auth.env.toml)​

These variables take precedence over the root workspace.env.toml. Excellent for swapping base URLs or headers for a specific microservice:

[variables]
# Define your workspace-wide global variables here.
# These will be automatically resolved by all request collections and suites.
base_url = "https://httpbin.org"

2. Collection-Level Config (auth.config.toml)​

Set localized timeout or retry behaviors specific to this domain's SLA requirements:

[config]
# Workspace-level request runner configurations.
# Timeout in milliseconds, request retries, delay, etc.
# timeout_ms = 5000
# max_retries = 3

3. Ordered Workflow Suite (auth.suite.toml)​

Orchestrates your folder's request nodes in a strict topological sequence:

[suite]
name = "Auth Workflow Suite"
description = "Modular ordered execution suite for Auth request workflows."
ordered = true

requests = [
    "requests/example.toml"
]

4. Interactive Request Template (requests/example.toml)​

Pre-loaded with clear explanations of request headers, assertions, and variable chaining to help new developers start writing tests instantly.

Step 3: Run Your New Collection​

To run the scaffolded collection out-of-the-box, execute its suite:

rumour run auth/auth.suite.toml

Expected Output:

  GET https://httpbin.org/get
  ✓ SUCCESS: /home/bugsfounder/workspace/my_testing_project/auth/requests/example.toml (235ms)
    ✓ auth/auth.suite.toml → PASS (1 Pass, 0 Fail, 0 Skip)

Multiple modules​

rumour new timelines
~/workspace/testing/recommended_setup/sectionForge main* ❯ rumour new timelines

  Collection 'timelines' successfully created!
  Location: /home/bugsfounder/workspace/testing/recommended_setup/sectionForge/timelines

  Scaffolded:
    • timelines/timelines.env.toml (Domain environment overrides)
    • timelines/timelines.config.toml (Domain runner configurations)
    • timelines/timelines.suite.toml (Ordered sequence runner suite)
    • timelines/requests/                 (Subfolder for API request TOMLs)
        └── requests/example.toml    (Documented template request)

  To run this collection's test suite:
    $ rumour run timelines/timelines.suite.toml

workspace Strucute​

sectionForge
├── auth
│   ├── auth.config.toml
│   ├── auth.env.toml
│   ├── auth.suite.toml
│   └── requests
│       └── example.toml
├── timelines
│   ├── requests
│   │   └── example.toml
│   ├── timelines.config.toml
│   ├── timelines.env.toml
│   └── timelines.suite.toml
├── sectionForge.config.toml
├── sectionForge.suite.toml
└── workspace.env.toml

5 directories, 11 files

🛑 Nested Workspaces (Anti-Nesting Protection)​

To maintain absolute structural integrity, prevent path-mapping loops, and keep variable scoping deterministic, Rumour actively blocks the creation of nested workspaces.

If you attempt to run rumour init inside a folder that is already a child or descendant of an active Rumour workspace, the engine will safely abort and print a clear, informative error:

~/workspace/testing/recommended_setup/swahira/sectionForge/timelines ❯ rumour init new_workspace

  ERROR: Cannot initialize a new workspace here because it is already nested inside an active Rumour workspace at:
  /home/bugsfounder/workspace/testing/recommended_setup/swahira

Nested Modules (Cascading Collections)​

For large-scale, enterprise APIs, you can organize your collections into cascading, hierarchical subdomains to perfectly match your API routes.

Rumour's scaffolding command (rumour new) is fully CWD-relative and context-aware. This means that when you are inside a collection directory and run rumour new, it will gracefully nest the new sub-collection inside it.

Example Walkthrough:​

# 1. Enter your main collection
cd sectionForge/timelines

# 2. Scaffold sub-collections relative to your active directory
rumour new published
rumour new history

Resulting Cascading Directory Tree:​

This context-aware behavior results in an incredibly clean, logically grouped folder structure:

sectionForge
   ├── auth
   │   ├── auth.config.toml
   │   ├── auth.env.toml
   │   ├── auth.suite.toml
   │   └── requests
   │       └── example.toml
   ├── timelines
   │   ├── history
   │   │   ├── history.config.toml
   │   │   ├── history.env.toml
   │   │   ├── history.suite.toml
   │   │   └── requests
   │   │       └── example.toml
   │   ├── published
   │   │   ├── published.config.toml
   │   │   ├── published.env.toml
   │   │   ├── published.suite.toml
   │   │   └── requests
   │   │       └── example.toml
   │   ├── requests
   │   │   └── example.toml
   │   ├── timelines.config.toml
   │   ├── timelines.env.toml
   │   └── timelines.suite.toml
   ├── sectionForge.suite.toml
   ├── sectionForge.config.toml
   └── workspace.env.toml

9 directories, 19 files

This ensures complete modular isolation at every layer while allowing child collections to dynamically inherit variable configurations from all parent/workspace envelopes!

Best Practices​

  1. Secure Your Secrets with Rumour Vault: Never store sensitive tokens or plaintext passwords directly in your environment configurations. Instead, use Rumour's built-in Encrypted Vault to store secrets securely, or supply variables dynamically at runtime:

    rumour run auth/auth.suite.toml -V api_key=runtime-override-secret

  2. Structuring for Organization (The Resolution Hierarchy): Rumour is incredibly flexible: even if you mix .env.toml, .config.toml, or .suite.toml files directly inside your requests/ folder, the execution engine handles it perfectly without errors.

    However, keeping them at the collection root is highly recommended strictly for clean structure and project hygiene.

    When resolving variables, Rumour always respects a clean Priority Hierarchy (from highest to lowest precedence):

    • Local Variables: Defined directly inside the request TOML's [variables] or [extract] block.
    • Collection-Level Variables: Defined in the modular <collection>.env.toml.
    • Workspace-Level Variables: Defined in the global workspace.env.toml.

    (Note: Dynamic command-line overrides supplied via the -V flag always take absolute top priority, overriding all of the above.)

  3. Cascading Configuration Inheritance & Merging Rules: Just like environment envelopes, modular config files (.config.toml) cascade and merge dynamically through your nested directory path (from the workspace root down to the leaf node):

    • Request Headers: Custom headers are accumulated cumulatively. For instance, a request in timelines/published/ will carry all headers defined in sectionForge.config.toml, timelines.config.toml, and published.config.toml seamlessly.
    • Config Variables & Settings: Runner settings (such as max_retries or timeout_ms) and configuration-level variables are merged dynamically. Deeper subdirectory files overwrite values defined in parent/workspace configurations.
    • Precedence Order: Leaf configuration overrides workspace root defaults.

  4. Orchestrating Master Suites for CI/CD Pipelines: For a comprehensive end-to-end integration run, link all domain-specific sequence suites together inside your global workspace-level suite (sectionForge.suite.toml):

    [suite]
    name = "sectionForge Global Master Suite"
    description = "Orchestrates all cascading modules sequentially for full system verification."
    ordered = true

    requests = [
        "auth/auth.suite.toml",
        "timelines/timelines.suite.toml",
        "timelines/published/published.suite.toml",
        "timelines/history/history.suite.toml"
    ]

    Executing rumour run sectionForge.suite.toml will trigger the entire cascading test suite sequentially, resolving all dynamic token extractions and generated post ID dependencies with 100% determinism!