Skip to main content
Glama

Run the unit tests

godot_test
Idempotent

Run the project's GUT or GdUnit4 tests headless in Godot 4.7 and return only test totals, each failing test with its res://file:line and failure message. Use it after a change to confirm the tests still pass.

Instructions

Run the project's GUT or GdUnit4 tests in Godot 4.7 headless and return only the totals and the failing tests, each with res://file:line and the failure message, plus script errors from the run. Use it after a change to see whether the tests still pass. Needs Godot on this machine and GUT (res://addons/gut) or GdUnit4 (res://addons/gdUnit4) in the project. framework picks one when both are installed; dirs chooses the test folders or scripts (default: the framework's config, else res://test and res://tests); filter runs only matching GUT tests. An error result when a test fails, or when Godot or a framework is missing. Test files are not changed; reports go to a temporary folder or .godot/godotwright/. To try input without writing tests use godot_play; for load errors only use godot_check.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "godot_test"
  }
}

Input Schema

NameRequiredDescriptionDefault
dirsNotest folders or scripts as res:// paths (default: the framework's config, else res://test and res://tests)
pathNoproject folder, or a file or folder inside it (relative to the server's folder; default: the current project)
filterNoGUT only: run only tests whose name contains this text
frameworkNowhich framework (default: whichever is installed)
timeout_secondsNotimeout of the run (default 600)

Output Schema

NameRequiredDescriptionDefault
okYes
testsYes
errorsYes
failedYes
passedYes
skippedYes
findingsYes
warningsYes
frameworkYes
truncatedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.0
    • changedInput schema / properties / path / description
      Previous value: -"The project folder, or any file or folder inside it (Godotwright walks up to project.godot). Relative paths start at the server's folder. Default: the current project."New value: +"project folder, or a file or folder inside it (relative to the server's folder; default: the current project)"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "errors": {
      +      "type": "number"
      +    },
      +    "failed": {
      +      "type": "number"
      +    },
      +    "findings": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "count": {
      +            "type": "number"
      +          },
      +          "file": {
      +            "type": "string"
      +          },
      +          "line": {
      +            "type": "number"
      +          },
      +          "message": {
      +            "type": "string"
      +          },
      +          "rule": {
      +            "type": "string"
      +          },
      +          "severity": {
      +            "enum": [
      +              "error",
      +              "warning",
      +              "info"
      +            ],
      +            "type": "string"
      +          },
      +          "source": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "severity",
      +          "message"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "framework": {
      +      "enum": [
      +        "gut",
      +        "gdunit"
      +      ],
      +      "type": "string"
      +    },
      +    "ok": {
      +      "type": "boolean"
      +    },
      +    "passed": {
      +      "type": "number"
      +    },
      +    "skipped": {
      +      "type": "number"
      +    },
      +    "tests": {
      +      "type": "number"
      +    },
      +    "truncated": {
      +      "type": "number"
      +    },
      +    "warnings": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "ok",
      +    "errors",
      +    "warnings",
      +    "findings",
      +    "truncated",
      +    "framework",
      +    "tests",
      +    "passed",
      +    "failed",
      +    "skipped"
      +  ],
      +  "type": "object"
      +}
  2. Changed1 schema field changedv0.1.1
    • changedInput schema / properties / path / description
      Previous value: -"Project directory or a path inside it (default: the current project)."New value: +"The project folder, or any file or folder inside it (Godotwright walks up to project.godot). Relative paths start at the server's folder. Default: the current project."
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes beyond the annotations by disclosing side effects (test files untouched, reports written to a temp folder or .godot/godotwright/), which explains the readOnlyHint=false, and by defining failure semantics (error result when a test fails or when Godot/framework is missing). It does not cover timeout behavior or what happens when both frameworks exist but framework is omitted beyond the default note.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return contract, then prerequisites, then parameter notes, then alternatives. A few clauses repeat schema defaults (dirs, filter), which is minor waste but keeps it readable as one paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be re-explained in depth, and annotations carry the safety profile. The description still covers prerequisites, side effects, error conditions, and sibling routing, leaving nothing an agent needs to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the description only needs to add context. It does add some: framework 'picks one when both are installed', filter is GUT-only, and dirs falls back to the framework's config then res://test and res://tests. These mostly restate schema descriptions, so the gain is modest.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (run GUT/GdUnit4 tests headless in Godot 4.7) plus the precise output shape (totals, failing tests with res://file:line and failure message, script errors). It explicitly distinguishes itself from the two closest siblings, godot_play and godot_check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a trigger ('use it after a change to see whether the tests still pass') and names exclusions with the condition that selects each alternative: godot_play for trying input without writing tests, godot_check for load errors only. Prerequisites (Godot on the machine, GUT or GdUnit4 addon present) are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.