# @gitzone/tstest
🧪 **A powerful, modern test runner for TypeScript** - making your test runs beautiful and informative!

## Availabililty and Links
* [npmjs.org (npm package)](https://www.npmjs.com/package/@gitzone/tstest)
* [code.foss.global (source)](https://code.foss.global/gitzone/tstest)

## Why tstest?

**tstest** is a TypeScript test runner that makes testing delightful. It's designed for modern development workflows with beautiful output, flexible test execution, and powerful features that make debugging a breeze.

### ✨ Key Features

- 🎯 **Smart Test Execution** - Run all tests, single files, or use glob patterns
- 🎨 **Beautiful Output** - Color-coded results with emojis and clean formatting
- 📊 **Multiple Output Modes** - Choose from normal, quiet, verbose, or JSON output
- 🔍 **Automatic Discovery** - Finds all your test files automatically
- 🌐 **Cross-Environment** - Supports Node.js and browser testing
- 📝 **Detailed Logging** - Optional file logging for debugging
- ⚡ **Performance Metrics** - See which tests are slow
- 🤖 **CI/CD Ready** - JSON output mode for automation

## Installation

```bash
npm install --save-dev @gitzone/tstest
# or with pnpm
pnpm add -D @gitzone/tstest
```

## Usage

### Basic Test Execution

```bash
# Run all tests in a directory
tstest test/

# Run a specific test file
tstest test/test.mycomponent.ts

# Use glob patterns
tstest "test/**/*.spec.ts"
tstest "test/unit/*.ts"
```

### Execution Modes

**tstest** intelligently detects how you want to run your tests:

1. **Directory mode** - Recursively finds all test files
2. **File mode** - Runs a single test file
3. **Glob mode** - Uses pattern matching for flexible test selection

### Command Line Options

| Option | Description |
|--------|-------------|
| `--quiet`, `-q` | Minimal output - perfect for CI environments |
| `--verbose`, `-v` | Show all console output from tests |
| `--no-color` | Disable colored output |
| `--json` | Output results as JSON |
| `--logfile` | Save detailed logs to `.nogit/testlogs/[testname].log` |

### Example Outputs

#### Normal Output (Default)
```
🔍 Test Discovery
   Mode: directory
   Pattern: test
   Found: 4 test file(s)

▶️  test/test.ts (1/4)
   Runtime: node.js
   ✅ prepare test (1ms)
   Summary: 1/1 PASSED

📊 Test Summary
┌────────────────────────────────┐
│ Total Files:                 4 │
│ Total Tests:                 4 │
│ Passed:                      4 │
│ Failed:                      0 │
│ Duration:                542ms │
└────────────────────────────────┘

ALL TESTS PASSED! 🎉
```

#### Quiet Mode
```
Found 4 tests
✅ test functionality works
✅ api calls return expected data
✅ error handling works correctly
✅ performance is within limits

Summary: 4/4 | 542ms | PASSED
```

#### Verbose Mode
Shows all console output from your tests, making debugging easier:
```
▶️  test/api.test.ts (1/1)
   Runtime: node.js
   Making API call to /users...
   Response received: 200 OK
   Processing user data...
   ✅ api calls return expected data (145ms)
   Summary: 1/1 PASSED
```

#### JSON Mode
Perfect for CI/CD pipelines:
```json
{"event":"discovery","count":4,"pattern":"test","executionMode":"directory"}
{"event":"fileStart","filename":"test/test.ts","runtime":"node.js","index":1,"total":4}
{"event":"testResult","testName":"prepare test","passed":true,"duration":1}
{"event":"summary","summary":{"totalFiles":4,"totalTests":4,"totalPassed":4,"totalFailed":0,"totalDuration":542}}
```

## Test File Naming Conventions

tstest supports different test environments through file naming:

| Pattern | Environment | Example |
|---------|-------------|---------|
| `*.ts` | Node.js (default) | `test.basic.ts` |
| `*.node.ts` | Node.js only | `test.api.node.ts` |
| `*.chrome.ts` | Chrome browser | `test.dom.chrome.ts` |
| `*.browser.ts` | Browser environment | `test.ui.browser.ts` |
| `*.both.ts` | Both Node.js and browser | `test.isomorphic.both.ts` |

### Writing Tests

tstest uses TAP (Test Anything Protocol) for test output. Use `@pushrocks/tapbundle` for the best experience:

```typescript
import { expect, tap } from '@push.rocks/tapbundle';

tap.test('my awesome test', async () => {
  const result = await myFunction();
  expect(result).toEqual('expected value');
});

tap.start();
```

## Advanced Features

### Glob Pattern Support

Run specific test patterns:
```bash
# Run all unit tests
tstest "test/unit/**/*.ts"

# Run all integration tests
tstest "test/integration/*.test.ts"

# Run multiple patterns
tstest "test/**/*.spec.ts" "test/**/*.test.ts"
```

### Automatic Logging

Use `--logfile` to automatically save test output:
```bash
tstest test/ --logfile
```

This creates detailed logs in `.nogit/testlogs/[testname].log` for each test file.

### Performance Analysis

In verbose mode, see performance metrics:
```
⏱️  Performance Metrics:
   Average per test: 135ms
   Slowest test: api integration test (486ms)
```

### CI/CD Integration

For continuous integration, combine quiet and JSON modes:
```bash
# GitHub Actions example
tstest test/ --json > test-results.json

# Or minimal output
tstest test/ --quiet
```

## Contribution

We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)

## License

> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh)
| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)

[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com)