npm package: @midi-dev/unit-test
Description: CI-focused test runner for NestJS projects using Jest
Latest version: 0.0.26
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @midi-dev/unit-test

> Gói test runner cho NestJS và Jest với tính năng CI/CD và báo cáo toàn diện.

## Giới thiệu

`@midi-dev/unit-test` là một test runner chuyên nghiệp được thiết kế để cung cấp trải nghiệm testing nhất quán và hiệu quả cho các dự án NestJS sử dụng Jest.

### Tính năng chính

- **Dual Mode**: CI mode cho automation và Dev mode cho development
- **Báo cáo đa dạng**: JSON, HTML với thông tin chi tiết
- **Coverage tích hợp**: Code coverage với Jest engine
- **Jest tối ưu**: Sử dụng Jest Node API trực tiếp
- **Auto-discovery**: Tự động phát hiện cấu hình Jest
- **Project Init**: Tự động thiết lập scripts trong package.json

## Cài đặt

```bash
npm i -D @midi-dev/unit-test jest jest-html-reporter
```

## Bắt đầu nhanh

### Bước 1: Khởi tạo project

```bash
npx midi-utc init
```

### Bước 2: Chạy tests

```bash
npm run test             # Chạy tất cả tests
npm run test:cov      # Chạy tests với coverage
npm run test:report   # Tạo HTML report
```

## Tham chiếu Scripts

### Scripts cơ bản

| Script        | Mô tả                                | Mode | Output                     |
| ------------- | ------------------------------------ | ---- | -------------------------- |
| `test`        | Chạy tất cả tests (development mode) | dev  | Console output, verbose    |
| `test:ci`     | Chạy tests cho CI/CD                 | ci   | JSON report, quiet         |
| `test:watch`  | Chạy tests và theo dõi thay đổi file | dev  | Console output, watch mode |
| `test:report` | Tạo HTML test report                 | dev  | HTML file                  |
| `test:cov`    | Chạy tests với code coverage         | dev  | Console + coverage summary |

### Scripts được tạo tự động

Khi chạy `npx midi-utc init`, các scripts sau sẽ được thêm vào `package.json`:

```json
{
  "scripts": {
    "test": "midi-utc --dev",
    "test:ci": "midi-utc --ci --report-json ./jest-report/jest-report.json",
    "test:watch": "midi-utc --dev --watch",
    "test:report": "midi-utc --dev --report-html ./jest-report/jest-report.html",
    "test:cov": "midi-utc --dev --coverage"
  }
}
```

## Options tham số

### Tùy chọn Mode

| Option  | Mô tả                        | Default | Mục đích              |
| ------- | ---------------------------- | ------- | --------------------- |
| `--dev` | Development mode (verbose)   | true    | Development hàng ngày |
| `--ci`  | CI mode (quiet, JSON report) | false   | CI/CD pipeline        |

### Tùy chọn Báo cáo

| Option                 | Mô tả                      | Default                                    | Format |
| ---------------------- | -------------------------- | ------------------------------------------ | ------ |
| `--report-json <path>` | Tạo JSON report            | `./jest-report/jest-report.json` (CI mode) | JSON   |
| `--report-html <path>` | Tạo HTML report (dev only) | -                                          | HTML   |

### Tùy chọn Coverage

| Option       | Mô tả             | Reporters                      | Mục đích               |
| ------------ | ----------------- | ------------------------------ | ---------------------- |
| `--coverage` | Bật code coverage | `json-summary`, `text`, `lcov` | Kiểm tra test coverage |

### Tùy chọn Jest

| Option                 | Mô tả                         | Default       | Ví dụ                     |
| ---------------------- | ----------------------------- | ------------- | ------------------------- |
| `--config <path>`      | Đường dẫn file cấu hình Jest  | Auto-discover | `--config jest.config.js` |
| `--bail`               | Dừng sau lỗi đầu tiên         | false         | `--bail`                  |
| `--max-workers <n>`    | Số worker processes           | Jest default  | `--max-workers 4`         |
| `--pass-with-no-tests` | Pass khi không tìm thấy tests | false         | `--pass-with-no-tests`    |

### Tùy chọn Development

| Option    | Mô tả                 | Mode     | Mục đích               |
| --------- | --------------------- | -------- | ---------------------- |
| `--watch` | Watch mode (dev only) | dev only | Development continuous |

### Tùy chọn Utility

| Option   | Mô tả                    | Mục đích          |
| -------- | ------------------------ | ----------------- |
| `--init` | Khởi tạo project scripts | Setup ban đầu     |
| `--help` | Hiển thị help message    | Hướng dẫn sử dụng |

## Hướng dẫn sử dụng theo tình huống

### Development hàng ngày

```bash
# Chạy tests cơ bản
npm run test

# Chạy tests với watch mode
npm run test:watch

# Kiểm tra coverage
npm run test:cov
```

### Before commit

```bash
# Chạy tests với báo cáo
npm run test:report
```

### CI/CD Pipeline

```bash
# CI mode với JSON report
npm run test:ci

# Hoặc trực tiếp với CLI
npx midi-utc --ci --max-workers 2
```

### Debugging và Analysis

```bash
# Chạy với verbose output
npx midi-utc --dev --config custom-jest.config.js

# Coverage chi tiết với HTML report
npx midi-utc --dev --coverage --report-html ./detailed-coverage.html
```

## Định dạng JSON Report

### Cấu trúc báo cáo cơ bản

```json
{
  "startTime": "2024-01-01T00:00:00.000Z",
  "endTime": "2024-01-01T00:00:10.000Z",
  "numTotalTests": 100,
  "numPassedTests": 95,
  "numFailedTests": 5,
  "numPendingTests": 0,
  "numTodoTests": 0
}
```

### Chi tiết test results

```json
{
  "testResults": [
    {
      "filepath": "/path/to/auth.controller.spec.ts",
      "status": "failed",
      "numPassingTests": 8,
      "numFailingTests": 2,
      "numPendingTests": 0,
      "numTodoTests": 0,
      "tests": [
        {
          "title": "should authenticate user",
          "status": "passed",
          "duration": 25
        },
        {
          "title": "should handle invalid credentials",
          "status": "failed",
          "duration": 15,
          "failureMessage": "Expected 401 but received 500"
        }
      ]
    }
  ]
}
```

### Coverage summary

```json
{
  "coverageSummary": {
    "lines": { "total": 1000, "covered": 850, "pct": 85 },
    "statements": { "total": 1100, "covered": 935, "pct": 85 },
    "functions": { "total": 200, "covered": 180, "pct": 90 },
    "branches": { "total": 300, "covered": 240, "pct": 80 }
  }
}
```

## Jest Configuration

### Auto-discovery order

Tool sẽ tự động tìm cấu hình Jest theo thứ tự:

1. `jest.config.ts`
2. `jest.config.js`
3. `jest.config.mjs`
4. `jest.config.cjs`
5. `jest.config.json`
6. `package.json` (trường jest)

### Custom configuration

```bash
# Sử dụng config tùy chỉnh
npx midi-utc --config ./custom/jest.config.js

# Kết hợp với options khác
npx midi-utc --config ./jest.ci.config.js --ci --coverage
```

## Performance và Tối ưu hóa

### Tips tối ưu performance

```bash
# Giảm workers cho máy yếu
npx midi-utc --max-workers 2

# Chạy nhanh cho development
npm run test:watch  # Sử dụng watch mode
```

## Error Handling và Exit Codes

| Exit Code | Mô tả                            | Action          |
| --------- | -------------------------------- | --------------- |
| `0`       | Tất cả tests passed              | Success         |
| `1`       | Có test failures                 | Check test logs |
| `2`       | Configuration hoặc runtime error | Check setup     |

### Xử lý lỗi thường gặp

```bash
# Lỗi không tìm thấy tests
npx midi-utc --pass-with-no-tests

# Lỗi cấu hình Jest
npx midi-utc --config ./jest.config.js

# Lỗi out of memory
npx midi-utc --max-workers 1
```

## Ví dụ Output

### Development mode

```bash
$ npm test

[midi-utc] Running tests in dev mode...

📊 Test Summary:
  Total: 150
  ✅ Passed: 145
  ❌ Failed: 3
  ⏭️ Pending: 2
  📝 Todo: 0

Test Suites: 3 failed, 12 passed, 15 total
Tests:       3 failed, 145 passed, 150 total
Time:        15.234s
```

### CI mode với coverage

```bash
$ npm run test:ci

[midi-utc] JSON report written to ./jest-report/jest-report.json

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files |   85.2  |   78.5   |   90.1  |   84.8  |
----------|---------|----------|---------|---------|-------------------
```

### Coverage report

```bash
$ npm run test:cov

[midi-utc] Coverage analysis:

📊 Coverage Summary:
  Statements: 935/1100 (85%)
  Branches: 240/300 (80%)
  Functions: 180/200 (90%)
  Lines: 850/1000 (85%)
```