Testform for Visual Studio Code

Declarative Test-as-Code orchestration for Git directly inside your editor.
Language Server Protocol (LSP), native Test Explorer, state management, variable autoloading, Gherkin formatting, and quality governance.

🌟 Overview

The Testform extension transforms Visual Studio Code into a full-featured Integrated Development Environment (IDE) for Test-as-Code.

Whether you are writing declarative test cases, orchestrating test runs, managing enterprise test plans, or executing speculative plans against your test management provider (GitHub, Jira, Zephyr, Xray, or local offline storage), Testform for VS Code delivers real-time language intelligence, instant execution feedback, and deep lifecycle tooling.

📚 Official Documentation

Comprehensive guides, API specifications, and interactive language references are available at the official documentation portal:

👉 Official Testform Documentation Portal

• Getting Started: Quickstart & Installation Guide
• Configuration Language: DSL, Blocks, Providers & State Reference
• CLI Reference: Testform CLI Commands & Flags
• Documentation Repository: fromeroc9/testform-docs

🚀 Key Features

1. ⚡ Gherkin & Testform DSL IntelliSense

• Expression Autocompletion: Native autocompletion for ${var.*}, ${local.*}, ${data.*}, ${module.*}, and environment variables ${env.*} directly inside .feature steps and docstrings.
• Built-in Functions: Full IntelliSense and argument snippet insertion for core functions:
  • Strings: lower(), upper(), trim(), trimprefix(), trimsuffix(), startswith(), endswith(), replace(), split(), join(), format(), substr().
  • Collections & Maps: contains(), coalesce(), lookup(), length(), element(), slice(), merge().
  • System & Encoding: env(), uuid(), timestamp(), jsonencode(), jsondecode(), file().
• Smart Tag Suggestions: Context-aware completion for identity tags (@tc-X, @tr-X, @tp-X) automatically calculating the next available sequential ID.
• Custom Field Tags: Auto-suggests custom fields and their permitted enum values (e.g. @priority:Critical, @component:Auth, @severity:Blocker).

2. 🔄 Multi-Layer Variable & Manifest Autoload

• Testform continuously monitors your workspace, aggregating variables and local definitions across:
  1. Base manifests (main.yml, testform.yml).
  2. Domain modular manifests (variable.yml, variables.yml, locals.yml, data.yml, resource.yml, output.yml).
  3. Environment auto-load files (*.vars.yml, *.vars.yaml) loaded in strict alphabetical order.
• Immediate autocompletion with live type badges, defaults, and source file locations.

3. 🔍 Go to Definition & Hover Documentation

• F12 / Ctrl+Click: Jump directly from any ${var.endpoint} or ${local.auth_token} reference in a .feature file to its YAML definition line.
• Rich Hover Cards: Hover over any variable, local, or module output to inspect its evaluated expression, default value, type, description, and source manifest path.
• Cross-File Dependency Navigation: Navigate @depends_on("path/to.case.feature.@tc-1") references with instant jump-to-target.

4. 🛡️ Real-Time Diagnostics & Quality Gates

• Undeclared Variables: Highlights ${var.foo} or ${local.bar} references that do not exist in workspace manifests as editor warnings.
• Dependency Directives (@depends_on): Detects empty dependency targets, self-dependencies, non-existent internal tags, and missing target feature files.
• Identity Uniqueness: Flags duplicate identity tags (@tc-X, @tr-X, @tp-X) before you run testform plan or push to version control.
• Schema Validation: In-editor schema validation for main.yml, variable.yml, and *.vars.yml.

5. 🧪 Native Test Explorer (VS Code Test Controller)

• Deep integration with VS Code's native Testing sidebar.
• Automatically discovers executable test suites (.run.feature) and individual test scenarios.
• Run tests directly from gutter Play icons next to scenarios or feature titles.
• Live State Synchronization: Watches testform.state and updates test statuses (Passed, Failed, Skipped, Unexecuted) dynamically as executions complete.

6. 📊 Testform Sidebar Views

Located in the dedicated Testform Activity Bar tab:

1. State Explorer (testform.views.state):

   • Hierarchical inspection of managed resources (testcase, testrun, testplan, custom data sources, outputs).
   • Visual status badges (e.g., tainted resources, verification checkmarks).
   • Inspect Resource: Opens formatted resource state JSON in an editor tab.
   • Taint / Untaint: Mark resources for recreation on next apply without terminal typing.
   • State Remove: Remove an item from the state ledger (testform state rm).
   • Force Unlock: Release stale state locks with guided lock ID prompts.

2. Modules & .testform View (testform.views.modules):

   • Declared Modules: Modules specified in main.yml with their source URLs and declared outputs.
   • Installed Modules: Inspect frozen copies inside .testform/modules/.
   • Local Policies: Custom quality rules located under .testform/policies/.
   • Cache & Environment: Quick access to .testform/environment, .testform/cache/backend.json, and .testform/cache/lock.json.

3. Reports & Analytics (testform.views.reports):

   • One-click report triggers: Test Case Summary, Test Run Summary, Detailed Runs, Test Plan Summary, Coverage Matrix, Traceability Matrix, and Quality Audit.
   • Instant export picker for Markdown, Microsoft Word (.docx), Microsoft Excel (.xlsx), JSON, or CSV.

7. 📑 Specs & Execution Hub (Webview Dashboard)

• Open a full-screen, interactive dashboard via Testform: Open Test Cases, Runs & Plans Hub.
• Search, filter by tags, and visualize all specifications across your repository.
• Jump directly to any feature file line or execute targeted speculative plans (testform plan -target=...) directly from the UI.

8. 🌐 Isolated Workspace Switcher

• View and switch between active workspaces (default, staging, production) from the status bar item $(layers) Testform: <workspace>.
• Automatically tracks .testform/environment.
• Prompt-based creation (testform workspace new <name>) and deletion of isolated test environments.

9. ✨ Intelligent Gherkin Formatter

• Format .feature files instantly via Shift+Alt+F / editor.action.formatDocument.
• Automatically aligns Feature, Rule, Background, Scenario, steps (Given/When/Then), DocStrings, and Data Tables.
• Full bilingual keyword support (English and Spanish: Característica, Regla, Antecedentes, Escenario, Dado, Cuando, Entonces, Y, Pero, Ejemplos).

⌨️ Command Palette Catalog

Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) and type Testform:

⚙️ Configuration Settings

Customize extension behavior in your settings.json:

{
  // Path to the testform executable binary (default: "testform" from PATH)
  "testform.executablePath": "testform",

  // Enable the Testform Gherkin formatter as the default formatter for .feature files
  "testform.format.enable": true,

  // Enable real-time syntax, variable resolution, and dependency diagnostics
  "testform.diagnostics.enable": true,

  // Automatically insert a leading space when completing field values immediately following '='
  "testform.editor.autoSpaceAfterEquals": true,

  // Enable native VS Code Test Controller integration (Test Explorer tree & gutter run icons)
  "testform.testController.enable": true,

  // Target address passed to 'testform apply' when executing a scenario play action
  // "testrun" targets the parent TestRun suite (e.g. testcycle/run.feature.@tr-1) to reconcile state
  // "testcase" targets the specific referenced TestCase address directly
  "testform.testController.scenarioPlayTarget": "testrun",

  // Target insertion format for scenario targets inside TestRun rules
  // "short" inserts '@tc-01'
  // "classic" inserts 'Magento/cart.case.feature.@tc-01'
  "testform.testrun.targetFormat": "short",

  // Trace communication between VS Code and the Testform Language Server
  "testform.trace.server": "off" // "off" | "messages" | "verbose"
}

Recommended .vscode/settings.json for Projects

{
  "[gherkin]": {
    "editor.defaultFormatter": "fromeroc9.testform",
    "editor.formatOnSave": true
  },
  "[yaml]": {
    "editor.insertSpaces": true,
    "editor.tabSize": 2
  }
}

💡 Code Snippets

Gherkin Snippets (.feature)

YAML Snippets (main.yml, variable.yml)

📦 Installation & Setup

Prerequisites

1. Node.js (v18.0.0 or higher).
2. Testform CLI installed globally:

   npm install -g @fromeroc9/testform
   

   Verify installation:

   testform --version
   

Installing the Extension

• From Visual Studio Code Marketplace: Search for Testform by fromeroc9 and click Install.
• Manual VSIX Installation:

  code --install-extension testform-dsl-1.0.0.vsix
  

🛠️ Contributing & Development

# 1. Clone repository
git clone https://github.com/fromeroc9/testform-vscode.git
cd testform-vscode

# 2. Install dependencies
npm install

# 3. Compile client and server bundles
npm run build

# 4. Launch debugging host in VS Code
# Press F5 in Visual Studio Code

# 5. Package as VSIX
npm run package

📋 Release Notes & Changelog

For a complete and detailed log of changes across versions, see CHANGELOG.md:

• v1.0.0: Official production release — Full-Screen Specs Hub, bilingual Gherkin LSP, native Test Explorer, state reconciliation, relational state explorer, and YAML manifest autoload.

📄 License

This extension is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).
See LICENSE for details.

Developed with ❤️ by Flavio Romero (flavio.arc9@gmail.com).