[!IMPORTANT] This repository is outdated and no longer maintained. A new version of Squish MCP is available in the Qt Customer Portal.

The new version equips AI agents with the capability of directly interacting with your application under test (AUT), which enables them to generate sensible test cases for complex applications such as Qt Creator, and reduces the amount of tokens required for generating tests. See the release announcement for more details.

Squish MCP v0.1.0 (outdated)

Squish Model Context Protocol (MCP) server enables AI agents to run and create Squish (documentation) test scripts and test suites and analyze the results.

Demo video of Squish MCP in action

Requirements

• uv — Python package manager (also takes care of the correct Python version)
• Squish (version 9.0 or later)
• GitHub Copilot (VS Code Extension) (version 0.40 or later)

Tested on Windows 11, macOS, and Ubuntu 22.04.

Known Limitations

• Supported AUTs. Only Qt Widgets and QML-based applications are currently tested.
• Real names should be enabled. Without enabling real names, the performance gains provided by Squish MCP are severely reduced. To enable real name generation, modify the snapshot filter file at <path-to-squish>/etc/qt_snapshot_filter.xml and change <realname exclude="yes"/> to <realname exclude="no"/>.
• Avoid spaces in paths. VS Code has issues with spaces in file paths, which can cause otherwise correct configurations to fail. See vscode#214931.

Installation

1. Clone the repository:

   git clone <repository-url>
   cd squish-mcp
   

2. Install Python dependencies:

   uv sync
   

3. Configure the MCP server in VS Code. The exact configuration entry will vary depending on your agent. For GitHub Copilot in VS Code, it may look like this (.vscode/mcp.json in your working directory):

   {
       "servers": {
           "SquishMCP": {
               "command": "uv",
               "args": ["run", "--directory", "<path-to-squish-mcp>", "squish_mcp"],
               "env": {
                   "SQUISH_PREFIX": "<path-to-squish>",
               }
           }
       }
   }
   

   MCP configuration documentation for VS Code (GitHub Copilot)

SQUISH_PREFIX=<path-to-squish> uv run --directory <path-to-squish-mcp> squish_mcp --transport http --host localhost --port 8000

{
    "servers": {
        "Squish-MCP": {
            "url": "http://localhost:8000/mcp",
            "type": "http"
        }
    }
}

Usage

Once your MCP server is configured and recognized by your agent, you are ready to start prompting. Most of the MCP tools operate in the context of a single test suite and accept the test_suite_path argument (a concrete suite_* directory path).

Example Usage

The examples below use the addressbook application bundled with Squish, found at <path-to-squish>/examples/qt/addressbook/addressbook.

Execute a Test Case / Test Suite

You can ask the agent to run either a full test suite or an individual test case. The agent will automatically determine paths and execute the appropriate Squish commands.

[!tip] Example prompt Run all Squish tests for the addressbook

The agent will locate the relevant tests and execute all it can relate to the addressbook. It may ask for clarifications if needed.

Generate Test Cases

You can ask the agent to generate Squish test cases for your application under test (AUT).

[!tip] Example prompt Create a new test suite for the addressbook application <path-to-squish>/examples/qt/addressbook/addressbook. Add a test to the suite that adds a contact in the addressbook and verifies its presence in the table.

The agent will create a test case and determine how to address individual objects (e.g. the add-button) in the application. It may reach out to the user, run intermediate test cases to programmatically scan the application's objects, or use existing test cases as reference.

If you already have Squish test cases available, you can reference them in the prompt to match the style and improve the quality of the generated test case.

Generate a BDD Test Case

Squish has its own implementation and structure for running BDD tests. Squish MCP is aware of this structure and can produce both feature files and step function implementations.

[!tip] Example prompt (assumes a generated test case from the prior steps) Convert the test case tst_add_contact into a BDD test

Squish MCP will create both test.py and test.feature files with proper BDD structure, including step definitions and feature file format.

Configuration

SQUISH-RULES.yaml

For adding general "rules of thumb" for the LLM to follow, you can customize project-specific patterns and conventions:

memories:
  requested_patterns:
    - pattern: "user asks for a screenshot verification"
      context: "Use the verify_image() function from global scripts"
    - pattern: "BDD step function with variable input"
      context: "Use |any| notation for variable parameters"
    - pattern: "Any time you, the LLM/ the AI agent, aren't sure of what to do in a test script"
      context: "Add a 'TODO: *' comment where you explain what needs to be done in a missing area."

You can use SQUISH-RULES.yaml.example for reference and create your own SQUISH-RULES.yaml in the src/squish_mcp/server/tools/analysis directory.

Environment variables

• SQUISH_GLOBAL_SCRIPTS: Directory storing scripts available for all Squish test cases, see Squish documentation for more information.

High-Level Architecture Overview

License

See the LICENSE file for details.