node-red-contrib-testmonitor/README.md

A comprehensive Node-RED wrapper for TestMonitor API providing test case management, test runs, milestones, and test result operations for test automation workflows

# node-red-contrib-testmonitor

A comprehensive Node-RED wrapper for the TestMonitor API providing test case management, test runs, milestones, and test result operations for test automation workflows.

## Features

- **Complete TestMonitor API Coverage**: Access all major TestMonitor endpoints
- **Authentication Management**: Secure API key authentication with connection testing
- **Intelligent Caching**: Configurable caching for improved performance
- **Error Handling**: Comprehensive error reporting and status indicators
- **Flexible Input/Output**: Support for both message properties and node configuration
- **Status Tracking**: Visual feedback for all operations

## Installation

### From Node-RED Palette Manager
1. Open Node-RED in your browser
2. Go to Menu → Manage Palette
3. Click the Install tab
4. Search for `node-red-contrib-testmonitor`
5. Click Install

### From npm
```bash
npm install node-red-contrib-testmonitor
```

### Manual Installation
```bash
cd ~/.node-red
npm install node-red-contrib-testmonitor
```

## Quick Start

1. **Add Credentials**: Drag a TestMonitor Credentials config node and configure your API details
2. **Add Operation Nodes**: Drag TestMonitor nodes for your desired operations
3. **Configure Operations**: Set up each node with the appropriate operation and parameters
4. **Connect and Deploy**: Wire up your flow and deploy

## Node Types

### TestMonitor Credentials
Configuration node for API authentication and connection management.

**Configuration:**
- **Base URL**: Your TestMonitor instance API URL
- **Project ID**: Numeric ID of your TestMonitor project
- **API Key**: Your TestMonitor API key (securely encrypted)

### TestMonitor TestCase
Manage test cases with full CRUD operations.

**Operations:**
- `get` - Retrieve a specific test case by ID
- `list` - List all test cases (optionally filtered by folder)
- `create` - Create a new test case
- `update` - Update an existing test case
- `delete` - Delete a test case

**Input Parameters:**
```javascript
msg.payload = {
    testCaseId: 123,           // Required for get, update, delete
    name: "Test Login",        // Required for create
    testCaseFolderId: 45,      // Folder for organization
    expected_result: "Success", // Expected outcome
    instructions: ["Step 1", "Step 2"], // Test steps
    tags: ["smoke", "authentication"],   // Tags for categorization
    description: "Test description",     // Custom field
    expected_value: "true",             // Custom field
    skip_time: 99                       // Custom field
};
```

### TestMonitor TestRun
Manage test runs and execution cycles.

**Operations:**
- `get` - Retrieve test run details
- `list` - List test runs (optionally filtered by milestone)
- `create` - Create a new test run
- `update` - Update test run properties
- `delete` - Delete a test run
- `getTestCases` - Get test cases in a test run
- `getTestResults` - Get test results for a test run
- `addTestCases` - Add test cases to a test run
- `openTestRun` - Open test run for execution (set draft=false)
- `closeTestRun` - Close test run for editing (set draft=true)

**Input Parameters:**
```javascript
msg.payload = {
    testRunId: 456,           // Required for most operations
    milestoneId: 789,         // Required for create
    name: "Sprint 1 Testing", // Test run name
    test_case_ids: [1, 2, 3], // For addTestCases operation
    draft: true,              // Draft status
    users: [3],               // Assigned users
    tags: ["sprint1"]         // Tags
};
```

### TestMonitor TestResult
Record and manage test execution results.

**Operations:**
- `get` - Retrieve test result details
- `list` - List test results (filtered by test run/case)
- `create` - Create a new test result
- `update` - Update test result
- `delete` - Delete test result
- `addComment` - Add comment to test result
- `addAttachment` - Upload file attachment
- `ensureExists` - Create or update test result

**Input Parameters:**
```javascript
msg.payload = {
    testResultId: 789,        // Required for get, update, delete
    testCaseId: 123,          // Required for create
    testRunId: 456,           // Required for create
    statusId: "passed",       // Status: passed, failed, blocked, not_tested, retest
    description: "Test completed successfully",
    comment: "Additional notes", // For addComment
    filePath: "/path/to/file"    // For addAttachment
};
```

### TestMonitor Milestone
Manage project milestones and releases.

**Operations:**
- `get` - Retrieve milestone details
- `list` - List all milestones in project
- `create` - Create a new milestone
- `update` - Update milestone properties
- `delete` - Delete milestone
- `getTestRuns` - Get test runs for milestone
- `getLastTestRun` - Get the most recent test run
- `createTestRun` - Create new test run under milestone

**Input Parameters:**
```javascript
msg.payload = {
    milestoneId: 101,               // Required for most operations
    name: "Release 2.0",            // Milestone name
    milestoneTypeId: "release",     // Type: release, feature, iteration, plan, sprint, version
    description: "Major release",   // Description
    ends_at: "2024-12-31",         // End date (YYYY-MM-DD)
    testRunName: "Release Testing"  // For createTestRun
};
```

### TestMonitor Project
Access project-level information and resources.

**Operations:**
- `get` - Get project information
- `getMilestones` - List project milestones
- `getMilestoneTypes` - Get available milestone types
- `getTestSuites` - List test case folders/suites
- `getTestCases` - List all project test cases
- `getTestRuns` - List project test runs
- `getCustomFields` - Get custom field definitions
- `getRequirements` - List project requirements
- `update` - Update project settings

**Input Parameters:**
```javascript
msg.payload = {
    milestoneId: 101,           // Filter test runs by milestone
    model: "test-cases",        // Model for custom fields
    filterTag: "api",           // Filter requirements by tag
    name: "Updated Project Name" // For update operation
};
```

## Configuration Examples

### Basic Test Execution Flow
```javascript
// 1. Get test cases from folder
msg.testCaseFolderId = 45;

// 2. Create test run
msg.payload = {
    operation: "create",
    milestoneId: 101,
    name: "Automated Test Run",
    test_cases: [1, 2, 3, 4, 5]
};

// 3. Record test results
msg.payload = {
    operation: "ensureExists",
    testCaseId: 1,
    testRunId: 456,
    statusId: "passed",
    description: "Test completed successfully"
};
```

### Test Case Management
```javascript
// Create test case
msg.payload = {
    operation: "create",
    name: "Verify User Login",
    testCaseFolderId: 45,
    expected_result: "User successfully logs in",
    instructions: [
        "Navigate to login page",
        "Enter valid credentials",
        "Click login button",
        "Verify dashboard loads"
    ],
    tags: ["authentication", "smoke"],
    description: "Verifies the user login functionality"
};
```

### Milestone and Test Run Setup
```javascript
// Create milestone
msg.payload = {
    operation: "create",
    name: "Sprint 3",
    milestoneTypeId: "sprint",
    description: "Sprint 3 development cycle",
    ends_at: "2024-03-31"
};

// Create test run under milestone
msg.payload = {
    operation: "createTestRun",
    milestoneId: 101,
    testRunName: "Sprint 3 Testing",
    draft: false
};
```

## Authentication

The package uses Bearer token authentication with the TestMonitor API:

1. Generate an API key from your TestMonitor account settings
2. Configure the TestMonitor Credentials node with:
   - Your TestMonitor instance URL
   - Project ID
   - API key
3. Use the "Test Connection" button to verify connectivity

## Caching

All nodes support intelligent caching for read operations:
- **Default Duration**: 5 minutes (300 seconds)
- **Configurable**: Adjust cache duration per node
- **Automatic**: Read operations are cached automatically
- **Cache Keys**: Generated based on operation and parameters

## Error Handling

The package provides comprehensive error handling:
- **Visual Status**: Node status shows current operation state
- **Error Messages**: Detailed error information in Node-RED debug
- **Graceful Degradation**: Failed operations don't crash flows
- **Validation**: Input validation with helpful error messages

## Status Indicators

Nodes display status using colored dots:
- **Grey**: Ready/idle
- **Blue**: Processing operation
- **Green**: Operation completed successfully
- **Red**: Error occurred

## Custom Fields

TestMonitor custom fields are supported:
- **Test Cases**: `description`, `expected_value`, `skip_time`
- **Automatic Processing**: Custom fields are extracted and included in responses
- **Create/Update**: Custom fields can be set during creation/updates

## Security

- **Encrypted Storage**: API keys are stored encrypted in Node-RED's credential system
- **HTTPS Only**: All API communications use HTTPS
- **Token Based**: Uses secure Bearer token authentication
- **No Logging**: Sensitive data is not logged

## Requirements

- **Node-RED**: Version 1.0.0 or higher
- **Node.js**: Version 14.0.0 or higher
- **TestMonitor Account**: With API access enabled
- **Network Access**: HTTPS connectivity to TestMonitor instance

## Dependencies

- `axios`: HTTP client for API requests
- `node-cache`: Intelligent caching system

## Support

For issues and feature requests:
- **GitHub Issues**: [Report Issues](https://github.com/MadnessEngineering/node-red-contrib-testmonitor/issues)
- **Documentation**: [TestMonitor API Docs](https://docs.testmonitor.com/)

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Changelog

### 1.0.0
- Initial release
- Full TestMonitor API coverage
- Comprehensive error handling
- Intelligent caching system
- Complete documentation