Tags API Validation Testing Guide

Tags API Validation Testing Guide

**Story:** 2.3 - Validate & Test Tags API **Status:** In Progress **Test Suite:** `test-tags-validation.js`

Overview

Comprehensive validation testing for all 5 Tags API methods implemented in the n8n Workflow Builder MCP Server:

• get_tags - List all tags with cursor-based pagination
• get_tag - Retrieve specific tag by ID
• create_tag - Create new tags
• update_tag - Update tag names
• delete_tag - Remove tags

Prerequisites

1. Running n8n Instance

You need access to a live n8n instance (v1.82.3 or later) with:

• Valid API key
• Permissions to create, update, and delete tags

2. Environment Configuration

Same as previous test suites - use either `.config.json` or `.env` file.

3. Built Project

npm run build

Running the Tests

Basic Test Execution

# 1. Build the project
npm run build

# 2. Start the MCP server (if not already running)
npm start &

# 3. Wait for server to start
sleep 3

# 4. Run tags validation tests
node test-tags-validation.js

Test Categories

1. get_tags Tests (4 tests)

Tests tag listing and pagination:

• List all tags
• Response structure validation
• Pagination limit
• Cursor-based pagination

2. create_tag Tests (3 tests)

Tests tag creation:

• Create tag with unique name
• Response structure validation
• Duplicate name handling (409 error expected)

3. get_tag Tests (3 tests)

Tests individual tag retrieval:

• Retrieve tag by ID
• Structure validation
• 404 error for non-existent ID

4. update_tag Tests (2 tests)

Tests tag name updates:

• Update tag name
• 404 error for non-existent ID

5. delete_tag Tests (2 tests)

Tests tag deletion:

• Delete and verify removal
• 404 error for non-existent ID

Expected Response Structures

Tag Object

{
  "id": "string",
  "name": "string",
  "createdAt": "ISO 8601 date",
  "updatedAt": "ISO 8601 date"
}

List Response

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "createdAt": "ISO 8601 date",
      "updatedAt": "ISO 8601 date"
    }
  ],
  "nextCursor": "string or null"
}

Key Testing Points

Tag Name Uniqueness

Tags must have unique names within an n8n instance. Attempting to create a duplicate will result in a 409 Conflict error.

Cursor-Based Pagination

Similar to executions API:

• Uses opaque cursor strings
• nextCursor field indicates more results available
• Efficient for large tag lists

Error Handling

Tests validate proper error responses:

• 404 Not Found for non-existent tag IDs
• 409 Conflict for duplicate tag names
• Proper error message format

Test Data Cleanup

The test suite automatically cleans up all created tags after completion (unless `runCleanup: false`).

**Cleanup behavior:**

• All tags created during tests are deleted
• Uses unique prefix TagTest_ for identification
• Automatic retry logic for failed deletions

Troubleshooting

Issue: "Duplic