diff --git a/astro.config.mjs b/astro.config.mjs index 5f7e1aa7..7492b37a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -98,7 +98,9 @@ export default defineConfig({ { label: 'Working With Plans', link: '/tutorials/working-with-plans'}, { label: 'Working With Jira', link: '/tutorials/working-with-jira'}, { label: 'Using AI in Testing', link: '/tutorials/using-ai-in-testing'}, - { label: 'MCP - Connect AI Assistant', link: '/tutorials/mcp-connection'}, + { label: 'MCP - Connect Claude', link: '/tutorials/connect-claude-to-testomat'}, + { label: 'MCP - Connect ChatGPT', link: '/tutorials/connect-chatgpt-to-testomat'}, + { label: 'MCP - Connect with a Config File', link: '/tutorials/mcp-connection'}, { label: 'Interacting via API', link: '/tutorials/interacting-via-api'}, { label: 'Set Up Read-Only Access', link: '/tutorials/set-up-read-only-access'}, { label: 'Migration from TestRail', link: '/tutorials/migration-from-testrail'}, @@ -430,6 +432,7 @@ export default defineConfig({ { label: 'YouTrack', link: '/integrations/issues-management/youtrack' }, { label: 'GitLab', link: '/integrations/issues-management/gitlab' }, { label: 'Shortcut', link: '/integrations/issues-management/shortcut' }, + { label: 'Plane', link: '/integrations/issues-management/plane' }, { label: 'Confluence', link: '/integrations/issues-management/confluence'}, ], }, diff --git a/src/content/docs/integrations/issues-management/images/plane/1-plane-create-token.png b/src/content/docs/integrations/issues-management/images/plane/1-plane-create-token.png new file mode 100644 index 00000000..1b625708 Binary files /dev/null and b/src/content/docs/integrations/issues-management/images/plane/1-plane-create-token.png differ diff --git a/src/content/docs/integrations/issues-management/images/plane/2-plane-token-created.png b/src/content/docs/integrations/issues-management/images/plane/2-plane-token-created.png new file mode 100644 index 00000000..b2bb865d Binary files /dev/null and b/src/content/docs/integrations/issues-management/images/plane/2-plane-token-created.png differ diff --git a/src/content/docs/integrations/issues-management/images/plane/3-plane-token-list.png b/src/content/docs/integrations/issues-management/images/plane/3-plane-token-list.png new file mode 100644 index 00000000..ff40544c Binary files /dev/null and b/src/content/docs/integrations/issues-management/images/plane/3-plane-token-list.png differ diff --git a/src/content/docs/integrations/issues-management/images/plane/4-connect-to-ims.png b/src/content/docs/integrations/issues-management/images/plane/4-connect-to-ims.png new file mode 100644 index 00000000..17b6a932 Binary files /dev/null and b/src/content/docs/integrations/issues-management/images/plane/4-connect-to-ims.png differ diff --git a/src/content/docs/integrations/issues-management/images/plane/5-connect-plane.png b/src/content/docs/integrations/issues-management/images/plane/5-connect-plane.png new file mode 100644 index 00000000..92d72ca5 Binary files /dev/null and b/src/content/docs/integrations/issues-management/images/plane/5-connect-plane.png differ diff --git a/src/content/docs/integrations/issues-management/images/plane/plane-integration.png b/src/content/docs/integrations/issues-management/images/plane/plane-integration.png new file mode 100644 index 00000000..9f0d6931 Binary files /dev/null and b/src/content/docs/integrations/issues-management/images/plane/plane-integration.png differ diff --git a/src/content/docs/integrations/issues-management/images/plane/plane-integration.svg b/src/content/docs/integrations/issues-management/images/plane/plane-integration.svg new file mode 100644 index 00000000..c2442559 --- /dev/null +++ b/src/content/docs/integrations/issues-management/images/plane/plane-integration.svg @@ -0,0 +1,53 @@ + + + + + + + + + + Plane integration flow + + + + + + + + + + Collect Values + Token, slug, and + project details. + + + + + Connect Plane + Add a profile and + test the connection. + + + + + Link Issues + Create or link Plane + work items. + + + + + Stay Synced + Defects and + requirements update. + + diff --git a/src/content/docs/integrations/issues-management/index.md b/src/content/docs/integrations/issues-management/index.md index 239d81f3..25e0e0b5 100644 --- a/src/content/docs/integrations/issues-management/index.md +++ b/src/content/docs/integrations/issues-management/index.md @@ -12,7 +12,7 @@ head: - tag: meta attrs: name: keywords - content: Testomat.io, issues management, Jira integration, GitHub issues, Azure DevOps, Linear, defect management, QA tools, test tracking, issue linking, automation, test defects, failed test + content: Testomat.io, issues management, Jira integration, GitHub issues, Azure DevOps, Linear, Plane, defect management, QA tools, test tracking, issue linking, automation, test defects, failed test --- import DirectoryLinks from /src/components/DirectoryLinks.astro; diff --git a/src/content/docs/integrations/issues-management/plane.md b/src/content/docs/integrations/issues-management/plane.md new file mode 100644 index 00000000..6974bf95 --- /dev/null +++ b/src/content/docs/integrations/issues-management/plane.md @@ -0,0 +1,137 @@ +--- +title: Plane +description: Connect your Plane workspace to Testomat.io to create and link Plane issues from tests and runs. Defects keep their title, description, status, severity, and comments in step with Plane, and severity maps to Plane priority both ways. +type: article +url: https://docs.testomat.io/integrations/issues-management/plane +head: + - tag: meta + attrs: + name: keywords + content: Plane integration, plane.so, Testomat.io, issues management, issue tracking, defect management, link test to issue, work item, severity mapping, self-hosted Plane, Personal Access Token, workspace slug +--- + +Connect your Plane workspace to a Testomat.io project to raise Plane work items from failing tests, link the ones you already have, and keep defects in step with Plane. + +![Plane integration flow: collect values, connect Plane, link issues, and stay synced](./images/plane/plane-integration.png) + +## Before You Start + +Collect these values from Plane. They all belong to the project you want to connect. + +| Value | Where to find it | +| --- | --- | +| **Personal Access Token** | Go to **Workspace settings**, then **Access Tokens** in Plane. See [Create a Personal Access Token](#create-a-personal-access-token). | +| **Workspace Slug** | The part of the URL after the domain: `app.plane.so/acme/projects` means the slug is `acme`. | +| **Project ID** | The project's UUID, for example `8b1f2e3c-4a5d-4e6f-9a1b-2c3d4e5f6a7b`. | +| **Project Identifier** | The short prefix in issue keys. If your work items look like `WEB-123`, the identifier is `WEB`. | + +## Create a Personal Access Token + +![The Create token window in Plane, opened from Workspace settings → Access Tokens](./images/plane/1-plane-create-token.png) + +1. In Plane, click **Settings** in the left sidebar. +2. Under **Developers**, select **Access Tokens**. +3. Click **Add access token**. +4. Enter a **Title** and **Description**. +5. Click **Set expiration date**, or turn on **Never expires**. +6. Click **Generate token**. + +:::note + +Copy the key from the **Key created** window before you click **Close** - Plane shows it only once. + +::: + +![The Key created window in Plane with the new access token and the copy button](./images/plane/2-plane-token-created.png) + +Plane also downloads a CSV file with the key, so you have a backup. + +Your token is ready - it appears in the **Access Tokens** list with the **Active** status. + +![The Access Tokens list in Plane with the new token marked Active](./images/plane/3-plane-token-list.png) + +## Connect Plane + +1. Open **Settings** and go to **Issues management**. +2. Click **Connect to IMS**. +3. Select **Plane** from the list. + +![Issues management page in Settings with the Connect to IMS button](./images/plane/4-connect-to-ims.png) + +In the connection creation window, fill in the following: + +1. Change the **Profile Name** if you want a different one. +2. Enter your **Workspace Slug**. +3. Paste your **Personal Access Token**. +4. Enter the **Project ID**. +5. Enter the **Project Identifier**. +6. Leave **Plane API URL** empty, unless you run Plane yourself. +7. Click **Test Connection**. Testomat.io checks the token, the workspace, and the project before anything is saved. +8. Click **Save**. + +![Plane connection form with the workspace slug, project ID, and project identifier filled in](./images/plane/5-connect-plane.png) + +The new profile appears on the **Issues management** page. A project can hold several profiles at once, so Plane can sit next to Jira or Linear. + +:::note + +**Plane API URL** is for self-hosted Plane only. When the field is empty, Testomat.io uses `https://api.plane.so`. + +::: + +## Create a Plane Issue from a Test + +1. Go to the **Tests** page. +2. Open a test or a suite. +3. Click the (`...`) menu and select **Link to Issue**. +4. Pick your Plane profile. +5. Click **Create new issue**. + +The work item appears in your Plane project with the description and a link back to the test, and its Plane URL shows on the test. You can do the same for a suite or for a failed test in a run report. + +## Link an Existing Plane Issue + +Paste the Plane URL into **Link to Issue**. Testomat.io recognizes it as Plane, pulls in the title, and shows it with the Plane icon. + +Plane gets a comment on the work item with a link back to Testomat.io, so the connection is visible from both sides. + +## Defects Stay in Step with Plane + +A defect raised from a Plane link keeps its title, description, status, severity, and comments in step with the work item. Edit the defect in Testomat.io and the change goes back to Plane. + +Severity and Plane priority map onto each other both ways: + +| Testomat.io severity | Plane priority | +| --- | --- | +| **critical** | urgent | +| **high** | high | +| **medium** | medium | +| **low** | low | +| none | no priority | + +## Keep Requirements Up to Date + +Plane items you add as requirements refresh **once a day**, so edits made in Plane reach Testomat.io on their own. + +When you need the latest version right away, refresh that requirement by hand: + +1. Go to the **Requirements** page. +2. Open the requirement. +3. Click the (`...`) menu. +4. Select **Refresh Requirement**. + +For everything requirements can do once they are in, see [AI-Requirements](https://docs.testomat.io/advanced/ai-powered-features/ai-requirements). + +## If This Doesn't Work + +- **Test Connection fails.** Check the **Workspace Slug** against the URL in Plane, and make sure the token belongs to a user who can see that project. +- **The issue search finds nothing.** Check the **Project ID**. It is the UUID, not the short prefix - the prefix goes into **Project Identifier**. +- **A link opens the API address instead of the issue.** Clear the **Plane API URL** field. It stays empty unless you run Plane yourself. +- **Nothing connects on a self-hosted Plane.** Fill in **Plane API URL** with your own API address. +- **A requirement still shows the old text.** The daily refresh has not run yet. Use **Refresh Requirement** to pull it now. + +## Next Steps + +- [Issues Management Systems](https://docs.testomat.io/integrations/issues-management) +- [Defects](https://docs.testomat.io/project/defects) +- [AI-Requirements](https://docs.testomat.io/advanced/ai-powered-features/ai-requirements) diff --git a/src/content/docs/tutorials/Migration-from-Qase.md b/src/content/docs/tutorials/Migration-from-Qase.md index 346dbc60..0b70007b 100644 --- a/src/content/docs/tutorials/Migration-from-Qase.md +++ b/src/content/docs/tutorials/Migration-from-Qase.md @@ -117,4 +117,4 @@ Match the type to Qase fields: a Qase selectbox or multiselect becomes a **List* * Moving from another tool? See [Import Tests From TestRail](https://docs.testomat.io/project/import-export/import/import-tests-from-testrail/), [Import Tests From QTest](https://docs.testomat.io/project/import-export/import/import-tests-from-qtest/), and [Import Tests From Testmo](https://docs.testomat.io/project/import-export/import/import-tests-from-testmo/). * Connect automated tests in [Import Tests From Source Code](https://docs.testomat.io/project/import-export/import/import-tests-from-source-code/). -* Connect an AI assistant to your project with [MCP - Connect AI Assistant](https://docs.testomat.io/tutorials/mcp-connection). \ No newline at end of file +* Connect an AI assistant to your project with [MCP - Connect with a Config File](https://docs.testomat.io/tutorials/mcp-connection). \ No newline at end of file diff --git a/src/content/docs/tutorials/connect-chatgpt-to-testomat.md b/src/content/docs/tutorials/connect-chatgpt-to-testomat.md new file mode 100644 index 00000000..3e35179b --- /dev/null +++ b/src/content/docs/tutorials/connect-chatgpt-to-testomat.md @@ -0,0 +1,96 @@ +--- +title: MCP - Connect ChatGPT +description: Connect ChatGPT to your Testomat.io project through the hosted MCP server. Add Testomat.io as a custom MCP server plugin with OAuth, sign in with your Testomat.io account, and ask about your tests in plain language. +type: article +url: https://docs.testomat.io/tutorials/connect-chatgpt-to-testomat +head: + - tag: meta + attrs: + name: keywords + content: MCP, Model Context Protocol, ChatGPT, ChatGPT plugins, Add custom MCP server, OAuth, connector URL, Testomat.io MCP Server, AI assistant, connect ChatGPT +--- + +Connect ChatGPT to your Testomat.io project. ChatGPT reads your tests, runs, and failures, and can create and update test cases for you. You sign in with your Testomat.io account, so ChatGPT gets the same access you have. No tokens to create, no config files to edit. + +![ChatGPT setup in 6 steps: copy the link, open Plugins, fill in the form, create the plugin, sign in, and start chatting](./images/connect-chatgpt-to-testomat/chatgpt-flow-radial.png) + +:::note + +The MCP Server is part of the AI-powered features. If the menu item is greyed out, turn them on first - see [AI-Powered Features](https://docs.testomat.io/advanced/ai-powered-features). If you use Claude instead, see [MCP - Connect Claude](https://docs.testomat.io/tutorials/connect-claude-to-testomat). + +::: + +## Copy the Connector URL + +1. Open the **Tests** page in the project you want to connect. +2. Click the (`...`) menu in the top-right corner and select **MCP Server**. +3. On the **Chats** tab, click the copy icon next to the connector URL. + +![The ⋯ menu on the Tests page, with MCP Server between Insights and AI Skills](./images/connect-claude-to-testomat/1-connect-mcp.png) + +The URL ends with your project name, so each project has its own. Copy it from the project you want ChatGPT to work with. + +![The Connect Testomat.io MCP Server window with the connector URL and the copy icon](./images/connect-claude-to-testomat/2-copy-connector.png) + +## Add Testomat.io as a Plugin + +1. In ChatGPT, click **Plugins** in the left sidebar. +2. Click **Add** in the top-right corner and select **Add custom MCP server**. + +![The Plugins page in ChatGPT with Add custom MCP server open under the Add button](./images/connect-chatgpt-to-testomat/1-add-custom-mcp-server.png) + +In a new pop-up, fill in the following: + +1. Enter `Testomat.io` in **Name**. +2. Under **Connection**, keep **Server URL** selected and paste the connector URL. +3. Choose **OAuth** in **Authentication**. +4. Select **I understand and want to continue**. +5. Click **Create as a plugin**. + +![The Add custom MCP server window with the name, connector URL, and OAuth authentication filled in](./images/connect-chatgpt-to-testomat/2-mcp-server-form.png) + +## Sign In to Testomat.io + +1. In the **Connect Testomat.io** window, click **Connect Testomat.io**. +2. Sign in to Testomat.io and approve the access ChatGPT is asking for. + +![The Connect Testomat.io window in ChatGPT with the Connect Testomat.io button](./images/connect-chatgpt-to-testomat/3-connect-testomat.png) + +Testomat.io now shows under **Installed** on the **Plugins** page. + +## Use Testomat.io in a Chat + +To start using your connector in a new chat right away: + +1. Open the **Testomat.io** plugin page. +2. Click **Try in chat**. + +![The Testomat.io plugin page in ChatGPT with the Try in chat button](./images/connect-chatgpt-to-testomat/4-try-in-chat.png) + +To use it in a new chat later, click **Plugins** below the message box and select **Testomat**. Ask something simple, like `How many tests are in my project?`, and you'll get an answer straight from your project. + +![The Plugins menu below the ChatGPT message box with Testomat selected](./images/connect-chatgpt-to-testomat/5-select-plugin.png) + +## What You Can Ask + +ChatGPT works with your tests in plain language. A few examples to start with: + +| You want to | Ask | +| --- | --- | +| See what failed | `Show me the failed tests from the last run` | +| Find gaps in coverage | `Find all tests tagged @smoke that have no steps` | +| Add a test | `Create a test "User logs in with valid credentials" in the Authentication suite` | + +ChatGPT can read and change the same things you can, so anything it writes appears in your project right away. + +## If This Doesn't Work + +- **There is no Add custom MCP server option.** Ask your workspace admin to turn them on. +- **Testomat is missing from the Plugins menu in a chat.** Check that Testomat.io shows under **Installed** on the **Plugins** page. If it doesn't, add it again. +- **Sign-in finishes but no tests appear.** Copy the URL again from the **Chats** tab. The URL is tied to one project, and a URL from another project will not work. + +## Next Steps + +- [MCP - Connect Claude](https://docs.testomat.io/tutorials/connect-claude-to-testomat) +- [MCP - Connect with a Config File](https://docs.testomat.io/tutorials/mcp-connection) +- [AI-Powered Features](https://docs.testomat.io/advanced/ai-powered-features) diff --git a/src/content/docs/tutorials/connect-claude-to-testomat.md b/src/content/docs/tutorials/connect-claude-to-testomat.md new file mode 100644 index 00000000..ed52011c --- /dev/null +++ b/src/content/docs/tutorials/connect-claude-to-testomat.md @@ -0,0 +1,96 @@ +--- +title: MCP - Connect Claude +description: Connect Claude to your Testomat.io project through the hosted MCP server. Copy the connector URL, add it as a custom connector in Claude, sign in with your Testomat.io account, and ask about your tests in plain language. +type: article +url: https://docs.testomat.io/tutorials/connect-claude-to-testomat +head: + - tag: meta + attrs: + name: keywords + content: MCP, Model Context Protocol, Claude, custom connector, OAuth, remote MCP server, Testomat.io MCP Server, AI assistant, test management, connect Claude +--- + +Connect Claude to your Testomat.io project and ask about your tests in plain language. Claude reads your tests, runs, and failures, and can create and update test cases for you. + +![You log in on the Testomat.io page, approve the access, and Claude gets a key you can revoke](./images/connect-claude-to-testomat/how-the-sign-in-works.png) + +You sign in with your Testomat.io account, so Claude gets the same access you have. No tokens to create, no config files to edit. + +This is the quickest way, and it works for Claude in the browser, on the desktop, and on your phone. If you use Cursor or OpenCode, connect them with [a config file](https://docs.testomat.io/tutorials/mcp-connection) instead. + +:::note + +The MCP Server is part of the AI-powered features. If the menu item is greyed out, turn them on first — see [AI-Powered Features](https://docs.testomat.io/advanced/ai-powered-features). + +::: + +## Copy the Connector URL + +1. Open the **Tests** page in the project you want to connect. +2. Click the **⋯** menu in the top-right corner and select **MCP Server**. +3. On the **Chats** tab, click the copy icon next to the connector URL. + +![The ⋯ menu on the Tests page, with MCP Server between Insights and AI Skills](./images/connect-claude-to-testomat/1-connect-mcp.png) + +The URL ends with your project name, so each project has its own. Copy it from the project you want Claude to work with. + +![The Connect Testomat.io MCP Server window with the connector URL and the copy icon](./images/connect-claude-to-testomat/2-copy-connector.png) + +:::note + +You can also reach this window from the **Chat with Tests** panel — the line **Prefer your own AI assistant?** links to the same place. + +::: + +## Add the Connector in Claude + +1. In Claude, open **Settings**. +2. Navigate to **Connectors**. +3. Click **+ Add** and select **Add custom connector**. +4. Name it `Testomat.io` and paste the URL into **Remote MCP server URL**. +5. Click **Add**, then **Connect**, and sign in to Testomat.io. +6. Review the access Claude is asking for, then click **Authorize**. + +![The Connectors page in Claude settings with Add custom connector open under the Add button](./images/connect-claude-to-testomat/3-add-custom-connector.png) + +Claude now shows **Testomat.io** in the connectors list. + +:::note + +On Claude Team and Enterprise plans, an organization owner adds the connector once in **Admin settings** → **Connectors**. Everyone else then connects their own Testomat.io account. + +::: + +## Claude Chat with Testomat.io + +1. Open a chat. +2. Click the **+** icon below the message box. +3. Navigate to **Connectors**. +4. Enable **Testomat.io**. + +![The tools menu in a Claude chat with the Testomat.io connector enabled](./images/connect-claude-to-testomat/4-enable-tool.png) + +## Work with Claude Chat + +Claude works with your tests in plain language. A few examples to start with: + +| You want to | Ask | +| --- | --- | +| See what failed | `Show me the failed tests from the last run` | +| Find gaps in coverage | `Find all tests tagged @smoke that have no steps` | +| Add a test | `Create a test "User logs in with valid credentials" in the Authentication suite` | + +Claude can read and change the same things you can, so anything it writes appears in your project right away. + +## If This Doesn't Work + +- **The MCP Server menu item is greyed out.** AI features are off for the project. Turn them on in the project settings, then reopen the menu. +- **Sign-in finishes but Claude shows no tests.** Check that the connector is enabled in the tools menu of the chat you are in. +- **The URL was pasted but nothing connects.** Copy it again from the **Chats** tab — the URL is tied to one project, and a URL from another project will not work. + +## Next Steps + +- [MCP - Connect ChatGPT](https://docs.testomat.io/tutorials/connect-chatgpt-to-testomat) +- [MCP - Connect with a Config File](https://docs.testomat.io/tutorials/mcp-connection) +- [Test Query Language (TQL)](https://docs.testomat.io/advanced/tql) +- [API Access](https://docs.testomat.io/advanced/api-access) diff --git a/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/1-add-custom-mcp-server.png b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/1-add-custom-mcp-server.png new file mode 100644 index 00000000..fb1cb509 Binary files /dev/null and b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/1-add-custom-mcp-server.png differ diff --git a/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/2-mcp-server-form.png b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/2-mcp-server-form.png new file mode 100644 index 00000000..feed770c Binary files /dev/null and b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/2-mcp-server-form.png differ diff --git a/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/3-connect-testomat.png b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/3-connect-testomat.png new file mode 100644 index 00000000..52350446 Binary files /dev/null and b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/3-connect-testomat.png differ diff --git a/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/4-try-in-chat.png b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/4-try-in-chat.png new file mode 100644 index 00000000..e039df3b Binary files /dev/null and b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/4-try-in-chat.png differ diff --git a/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/5-select-plugin.png b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/5-select-plugin.png new file mode 100644 index 00000000..096f3bf3 Binary files /dev/null and b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/5-select-plugin.png differ diff --git a/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/chatgpt-flow-radial.png b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/chatgpt-flow-radial.png new file mode 100644 index 00000000..34aa6d38 Binary files /dev/null and b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/chatgpt-flow-radial.png differ diff --git a/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/chatgpt-flow-radial.svg b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/chatgpt-flow-radial.svg new file mode 100644 index 00000000..477ea5c1 --- /dev/null +++ b/src/content/docs/tutorials/images/connect-chatgpt-to-testomat/chatgpt-flow-radial.svg @@ -0,0 +1,55 @@ + + + + + + + +ChatGPT setup in 6 steps + + + + + + + + + +1. Copy the Link +from MCP Server + + + +2. Open Plugins +in ChatGPT, click Add + + + +3. Fill In the Form +name, link, and OAuth + + + +4. Create the Plugin +tick the box, then create + + + +5. Sign In +to your Testomat.io + + + +6. Start Chatting +Try in chat, then ask + diff --git a/src/content/docs/tutorials/images/connect-claude-to-testomat/1-connect-mcp.png b/src/content/docs/tutorials/images/connect-claude-to-testomat/1-connect-mcp.png new file mode 100644 index 00000000..420495b2 Binary files /dev/null and b/src/content/docs/tutorials/images/connect-claude-to-testomat/1-connect-mcp.png differ diff --git a/src/content/docs/tutorials/images/connect-claude-to-testomat/2-copy-connector.png b/src/content/docs/tutorials/images/connect-claude-to-testomat/2-copy-connector.png new file mode 100644 index 00000000..e66a72d2 Binary files /dev/null and b/src/content/docs/tutorials/images/connect-claude-to-testomat/2-copy-connector.png differ diff --git a/src/content/docs/tutorials/images/connect-claude-to-testomat/3-add-custom-connector.png b/src/content/docs/tutorials/images/connect-claude-to-testomat/3-add-custom-connector.png new file mode 100644 index 00000000..c9a81d86 Binary files /dev/null and b/src/content/docs/tutorials/images/connect-claude-to-testomat/3-add-custom-connector.png differ diff --git a/src/content/docs/tutorials/images/connect-claude-to-testomat/4-enable-tool.png b/src/content/docs/tutorials/images/connect-claude-to-testomat/4-enable-tool.png new file mode 100644 index 00000000..504b46b0 Binary files /dev/null and b/src/content/docs/tutorials/images/connect-claude-to-testomat/4-enable-tool.png differ diff --git a/src/content/docs/tutorials/images/connect-claude-to-testomat/how-the-sign-in-works.png b/src/content/docs/tutorials/images/connect-claude-to-testomat/how-the-sign-in-works.png new file mode 100644 index 00000000..fcfdbaa5 Binary files /dev/null and b/src/content/docs/tutorials/images/connect-claude-to-testomat/how-the-sign-in-works.png differ diff --git a/src/content/docs/tutorials/index.mdx b/src/content/docs/tutorials/index.mdx index fcc873ad..602bb702 100644 --- a/src/content/docs/tutorials/index.mdx +++ b/src/content/docs/tutorials/index.mdx @@ -11,7 +11,9 @@ A tutorial is a short, step-by-step guide that walks you through one real task i - **Working With Plans** - build a plan once, then launch it as a run again and again. - **Working With Jira** - connect Testomat.io to Jira to link tests to issues. Report bugs without leaving your run. - **Using AI in Testing** - let AI create test data, summarize a suite, and answer questions about tests. -- **MCP - Connect AI Assistant** - connect Claude, Cursor, or OpenCode to the project through the MCP Server. +- **MCP - Connect Claude** - paste one connector URL into Claude and sign in with your Testomat.io account. +- **MCP - Connect ChatGPT** - do the same in ChatGPT, with a custom MCP server plugin and OAuth. +- **MCP - Connect with a Config File** - connect Cursor, Claude Desktop, or OpenCode by adding an MCP config file with your project token. - **Interacting via API** - pull tests and create runs from code. - **Set Up Read-Only Access** - give a client a safe way to look at your tests without changing anything. - **Migration from TestRail** - already have tests in TestRail? Bring them into Testomat.io. diff --git a/src/content/docs/tutorials/mcp-connection.md b/src/content/docs/tutorials/mcp-connection.md index a861ec15..1ba36968 100644 --- a/src/content/docs/tutorials/mcp-connection.md +++ b/src/content/docs/tutorials/mcp-connection.md @@ -1,6 +1,6 @@ --- -title: MCP - Connect AI Assistant -description: Learn how to connect an AI assistant to Testomat.io through the MCP Server. This guide walks you through getting your project token and project ID, adding the config to Claude Desktop, Cursor, or OpenCode, checking the connection, and what your assistant can do with your tests, suites, and runs. +title: MCP - Connect with a Config File +description: Connect Cursor, Claude Desktop, or OpenCode to Testomat.io by adding an MCP config file with your project token. Get the token and project ID, paste the config, check the connection, and see what your assistant can do with your tests, suites, and runs. type: article url: https://docs.testomat.io/tutorials/mcp-connection head: @@ -15,11 +15,11 @@ head: content: MCP, Model Context Protocol, Testomat.io MCP Server, AI assistant, Claude Desktop, Cursor, OpenCode, project token, project ID, mcp.json config, Public API v2, TQL, test suites, test runs, npx testomatio mcp, test management, AI test automation --- -Welcome! - In this tutorial, you will learn how you can connect Claude, Cursor, or OpenCode to your Testomat.io project through the MCP Server. After that, your assistant reads your tests, searches them, and manages runs for you, without you opening the app. -![MCP connection setup chart](./images/mcp-connection/mcp-setup-flow.png) +This tutorial sets up a config file with a project token, which is what Cursor, OpenCode, and Claude Desktop need. If you use Claude or ChatGPT in the browser, [MCP - Connect Claude](https://docs.testomat.io/tutorials/connect-claude-to-testomat) and [MCP - Connect ChatGPT](https://docs.testomat.io/tutorials/connect-chatgpt-to-testomat) are quicker — you sign in with your account, with nothing to configure. + +![Copy your token, add the config, restart the assistant, then ask it to list your suites](./images/mcp-connection/mcp-setup-flow.png) **Before you start:** @@ -27,7 +27,7 @@ In this tutorial, you will learn how you can connect Claude, Cursor, or OpenCode * A project in Testomat.io * Claude Desktop, Cursor, or OpenCode installed -**Get your token and project ID** +## Get Your Token and Project ID Your assistant needs two values from your project. @@ -39,17 +39,19 @@ Your assistant needs two values from your project. Use a project token, not a general one. A general token opens every project you have access to. See [API Access](https://docs.testomat.io/advanced/api-access/). -## Add the config to your assistant +## Add the Config to Your Assistant Follow the section for the assistant you use, and skip the other two. -Your token gives the assistant full access to the project, and anyone who can prompt the assistant can reach that data. +:::caution + +Treat your token like a password. It gives the assistant full access to the project, and anyone who can prompt the assistant can reach that data. -Treat your token like a password. If you use the project-level `.cursor/mcp.json`, add this file to `.gitignore` before saving the token. +If you use the project-level `.cursor/mcp.json`, add this file to `.gitignore` before saving the token. You can also use the global `~/.cursor/mcp.json`, which keeps the token outside the project repository. Never commit or share a config file containing your token. -Alternatively, use the global `~/.cursor/mcp.json` so the token is stored outside the project repository. Never commit or share a config file containing your token. +::: -### If you use Cursor +### If You Use Cursor 1. Open the file `.cursor/mcp.json` in your project. Create it if it isn't there. 2. Paste this config: @@ -73,7 +75,7 @@ Alternatively, use the global `~/.cursor/mcp.json` so the token is stored outsid To use the same connection in all your projects, edit `~/.cursor/mcp.json` instead. -### If you use Claude Desktop +### If You Use Claude Desktop 1. Open your Claude config file. Create it if it isn't there. * On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` @@ -96,7 +98,7 @@ To use the same connection in all your projects, edit `~/.cursor/mcp.json` inste 4. Save the file. 5. Restart Claude Desktop. -### If you use OpenCode +### If You Use OpenCode 1. Open the file `opencode.json` in your project root. Create it if it isn't there. 2. Paste this config: @@ -121,13 +123,13 @@ To use the same connection in all your projects, edit `~/.cursor/mcp.json` inste To use the same connection in all your projects, edit `~/.config/opencode/opencode.json` instead. -## Check that it worked +## Check That It Worked -![MCP connection check](./images/mcp-connection/mcp-check-connection.png) +![Ask the assistant to list your suites, it answers with your real suite names, and the connection is live](./images/mcp-connection/mcp-check-connection.png) Ask your assistant: **list my test suites**. If it answers with the real suite names from your project, the connection is live. -## What you can do +## What You Can Do Once connected, your assistant works with your project through [Public API v2](https://docs.testomat.io/advanced/api-access/#public-api-v2). It can: @@ -138,7 +140,7 @@ Once connected, your assistant works with your project through [Public API v2](h * Search tests and runs with [TQL](https://docs.testomat.io/advanced/tql/) * Launch, finish, and rerun a run. -## If this doesn't work +## If This Doesn't Work * **The assistant answers from general knowledge instead of your project data** - the config did not load. Check that the file path and the file name are correct, then restart the assistant. * **You get an access or "denied" error** - the token or project ID is wrong, or the token was revoked. Copy both again from the **API Key** page. @@ -147,6 +149,7 @@ Once connected, your assistant works with your project through [Public API v2](h ## Next Steps +* Prefer signing in instead of editing a config file? See [MCP - Connect Claude](https://docs.testomat.io/tutorials/connect-claude-to-testomat) or [MCP - Connect ChatGPT](https://docs.testomat.io/tutorials/connect-chatgpt-to-testomat). * Need to establish a connection with Testomat.io? See [API Access](https://docs.testomat.io/advanced/api-access/) for more details. * Learn how to customize your test syntax at [Test Query Language (TQL)](https://docs.testomat.io/advanced/tql/). * Read [Interacting via API](https://docs.testomat.io/tutorials/interacting-via-api/) to learn to interact with Testomat.io directly. \ No newline at end of file