js-tests-results-collector/README.md

Universal test results collector for Jest, Jasmine, Mocha, Cypress, and Playwright that sends results to Buddy Works API

# JS Tests Results Collector

Universal test results collector for Jest, Jasmine, Mocha, Cypress, Playwright, and Vitest that sends results to Buddy Works API in real-time.

## Features

- 🚀 **Real-time reporting** - Test results are sent immediately after each test completion
- 🔧 **Multi-framework support** - Works with Jest, Jasmine, Mocha, Cypress, Playwright, and Vitest
- 📊 **Buddy Works integration** - Direct integration with Buddy Works Unit Tests API
- ⚡ **Non-blocking** - Won't slow down your test execution
- 🛡️ **Error resilience** - API failures won't break your test runs
- 🔍 **Debug support** - Built-in logging for troubleshooting

## Installation

```bash
npm install js-tests-results-collector --save-dev
```

## Configuration

### Authentication

The Buddy Works API uses OAuth2 authentication with Bearer tokens. You need to generate an access token in your Buddy Works workspace settings.

To get an access token:
1. Go to your Buddy Works workspace
2. Navigate to **Workspace Settings** → **Developer API**
3. Enable the API if not already enabled
4. Generate or use an existing Personal Access Token

### API Endpoints

Buddy Works has different API endpoints depending on your region and installation type:

- **US Region (default)**: `https://api.buddy.works`
- **EU Region**: `https://api.eu.buddy.works` 
- **On-premise**: `https://your-domain.buddy.works`

Set the appropriate endpoint using the `BUDDY_API_BASE_URL` environment variable.

### Environment Variables

Set the following environment variables:

```bash
# Required
BUDDY_WORKSPACE_DOMAIN=your-domain
BUDDY_PROJECT_NAME=your-project
BUDDY_FOLDER_ID=123                                    # must be an integer
BUDDY_ACCESS_TOKEN=your-oauth-access-token

# API Endpoint (choose based on your region/installation)
BUDDY_API_BASE_URL=https://api.buddy.works            # US region (default)
# BUDDY_API_BASE_URL=https://api.eu.buddy.works       # EU region
# BUDDY_API_BASE_URL=https://your-domain.buddy.works  # On-premise installation

# Optional
BUDDY_RUN_BRANCH=main                                  # defaults to current git branch
BUDDY_REF_TYPE=BRANCH                                  # defaults to BRANCH  
BUDDY_RUN_COMMIT=abc123                                # defaults to current git commit
BUDDY_RUN_PRE_COMMIT=def456                            # defaults to current git commit
BUDDY_RUN_HASH=build-123                               # optional build identifier
BUDDY_RUN_URL=https://example.com/builds/123           # optional build URL
BUDDY_SOURCE=API                                       # defaults to API
BUDDY_DEBUG=true                                       # enable debug logging
```

## Usage

### Jest

Add the reporter to your Jest configuration:

**jest.config.js:**
```javascript
module.exports = {
  reporters: [
    'default',
    'js-tests-results-collector/jest'
  ]
};
```

**Or in package.json:**
```json
{
  "jest": {
    "reporters": [
      "default",
      "js-tests-results-collector/jest"
    ]
  }
}
```

### Mocha

Use the reporter with the `--reporter` flag:

```bash
mocha --reporter js-tests-results-collector/mocha test/**/*.js
```

**Or in package.json:**
```json
{
  "scripts": {
    "test": "mocha --reporter js-tests-results-collector/mocha test/**/*.js"
  }
}
```

### Jasmine

Add the reporter to your Jasmine configuration:

**spec/support/jasmine.json:**
```json
{
  "spec_dir": "spec",
  "spec_files": ["**/*[sS]pec.js"],
  "helpers": [
    "helpers/**/*.js",
    "js-tests-results-collector/jasmine"
  ]
}
```

### Cypress

Add the reporter to your Cypress configuration:

**cypress.config.js:**
```javascript
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    reporter: 'js-tests-results-collector/cypress',
    // ... other config
  },
});
```

### Playwright

Add the reporter to your Playwright configuration:

**playwright.config.js:**
```javascript
module.exports = {
  reporter: [
    ['list'],
    ['js-tests-results-collector/playwright']
  ],
  // ... other config
};
```

### Vitest

Add the reporter to your Vitest configuration:

**vitest.config.js:**
```javascript
export default {
  test: {
    reporters: [
      'default',
      'js-tests-results-collector/vitest'
    ]
  }
};
```

**Or in package.json:**
```json
{
  "scripts": {
    "test": "vitest run --reporter=default --reporter=js-tests-results-collector/vitest"
  }
}
```

## How It Works

1. **Session Creation**: When tests start, a session is created via Buddy Works API
2. **Real-time Reporting**: Each test result is sent immediately after completion
3. **Result Mapping**: Framework-specific results are mapped to Buddy's format
4. **Error Handling**: API failures are logged but don't interrupt test execution

## API Integration

The collector integrates with Buddy Works Unit Tests API:

### Session Creation
```bash
POST /workspaces/{domain}/projects/{projectName}/unit-tests/folders/{folderId}/sessions
```

### Test Case Submission
```bash
PUT /workspaces/{domain}/projects/{projectName}/unit-tests/folders/{folderId}/sessions/{sessionId}/cases
```

## Test Result Format

Test results are mapped to the following format:

```json
{
  "name": "Test case name",
  "suite_name": "Test suite name",
  "suite_id": "unique-suite-id",
  "classname": "test.file.path",
  "status": "PASSED|FAILED|SKIPPED|ERROR",
  "time": 1.234,
  "data": "Error message or additional data"
}
```

## Debugging

Enable debug logging to troubleshoot issues:

```bash
BUDDY_DEBUG=true npm test
```

This will output detailed logs about:
- Session creation
- Test result submissions
- API responses
- Error details

## Examples

Check the `examples/` directory for complete configuration examples:

- `examples/jest-example/` - Jest configuration
- `examples/mocha-example/` - Mocha configuration  
- `examples/jasmine-example/` - Jasmine configuration
- `examples/cypress-example/` - Cypress configuration
- `examples/playwright-example/` - Playwright configuration
- `examples/vitest-example/` - Vitest configuration

## Contributing

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

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- Check the debug logs with `BUDDY_DEBUG=true`
- Review the examples in the `examples/` directory
- Open an issue on GitHub

## Changelog

### 1.0.0
- Initial release
- Support for Jest, Jasmine, Mocha, Cypress, Playwright, and Vitest
- Real-time test result reporting
- Buddy Works API integration