@epikodelabs/testify 1.0.16 → 1.0.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +290 -257
  3. package/package.json +1 -1
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 Oleksii Shepel
3
+ Copyright (c) 2026 Oleksii Shepel
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -2,27 +2,43 @@
2
2
 
3
3
  A flexible test runner for Jasmine that supports multiple execution environments with built-in TypeScript compilation, hot module reloading, and code coverage.
4
4
 
5
- ## Features
5
+ > ⚖️ “*testify doesn't mock the browser. It invites the browser into the courtroom and asks it to testify under oath.*”
6
6
 
7
- - **Multiple Execution Environments**
8
- - Real browsers (Chrome, Firefox, Safari) for DOM and browser API testing
9
- - Headless browsers for CI/CD pipelines
10
- - Node.js for fastest unit test execution
11
-
12
- - **Developer Experience**
13
- - Hot Module Reload (HMR) for instant test feedback
14
- - TypeScript compilation with source maps
15
- - Interactive browser-based test reporter
16
- - VS Code debug integration
17
-
18
- - **Testing Capabilities**
19
- - Istanbul code coverage reporting
20
- - Configurable test execution order and randomization
21
- - Cross-environment test compatibility
7
+ <p align="center">
8
+ <a href="https://github.com/epikodelabs/testify/actions/workflows/build.yml">
9
+ <img src="https://github.com/epikodelabs/testify/actions/workflows/build.yml/badge.svg?branch=main" alt="Build Status">
10
+ </a>
11
+ <a href="https://www.npmjs.com/package/@epikodelabs/testify">
12
+ <img src="https://img.shields.io/npm/v/@epikodelabs/testify.svg?style=flat-square" alt="NPM Version">
13
+ </a>
14
+ <a href="https://www.npmjs.com/package/@epikodelabs/testify">
15
+ <img src="https://img.shields.io/npm/dm/@epikodelabs/testify.svg?style=flat-square" alt="NPM Downloads">
16
+ </a>
17
+ </p>
18
+
19
+ ## Give a Star on GitHub
20
+
21
+ If testify helps you, please give it a star: https://github.com/epikodelabs/testify
22
22
 
23
23
  ---
24
24
 
25
- ## Installation
25
+ ## ✨ Why testify
26
+
27
+ **testify** is a modern test runner built for Jasmine that bridges the gap between fast unit testing and real browser testing. Whether you need blazing-fast feedback loops in Node.js or full DOM testing in actual browsers (yes, *actual* browsers—not JSDOM pretending to be one), testify adapts to your workflow with hot module reloading, TypeScript-first design, and zero-config coverage reporting. It's like having a Swiss Army knife for testing, except it actually works and won't get confiscated at the airport.
28
+
29
+ ### Highlights
30
+
31
+ - 🌐 Real browsers (Chrome, Firefox, Safari) for DOM and browser API testing
32
+ - ⚡ Node.js execution for lightning-fast unit tests
33
+ - 🔥 Hot Module Reload for instant test feedback during development
34
+ - 📦 TypeScript compilation with source maps out of the box
35
+ - 📊 Istanbul code coverage with beautiful HTML reports
36
+ - 🎯 Interactive browser-based test reporter
37
+ - 🔧 VS Code debug integration for single-spec debugging
38
+
39
+ ---
40
+
41
+ ## 📦 Installation
26
42
 
27
43
  ```bash
28
44
  # Install the test runner
@@ -34,9 +50,9 @@ npx playwright install
34
50
 
35
51
  ---
36
52
 
37
- ## Quick Start
53
+ ## ⚡️ Quick start
38
54
 
39
- ### 1. Initialize Configuration
55
+ ### 1. Initialize configuration
40
56
 
41
57
  ```bash
42
58
  npx testify init
@@ -56,7 +72,7 @@ This creates `testify.json` with sensible defaults:
56
72
  }
57
73
  ```
58
74
 
59
- ### 2. Write Jasmine Tests
75
+ ### 2. Write Jasmine tests
60
76
 
61
77
  Create `.spec.ts` files in your test directory:
62
78
 
@@ -83,7 +99,7 @@ describe('Calculator', () => {
83
99
  });
84
100
  ```
85
101
 
86
- ### 3. Run Your Tests
102
+ ### 3. Run your tests
87
103
 
88
104
  ```bash
89
105
  # Development: Interactive browser mode
@@ -104,11 +120,11 @@ npx testify --watch
104
120
 
105
121
  ---
106
122
 
107
- ## Execution Modes
123
+ ## 🎯 Execution modes
108
124
 
109
- ### Browser Mode (Default)
125
+ ### 🌐 Browser mode (Default)
110
126
 
111
- **Best for:** Development and debugging
127
+ **Best for:** Development and debugging (and feeling like a real developer)
112
128
 
113
129
  ```bash
114
130
  npx testify
@@ -116,12 +132,13 @@ npx testify
116
132
 
117
133
  - Opens `http://localhost:8888` in your default browser
118
134
  - Interactive HTML test reporter with Jasmine UI
119
- - Full browser DevTools for debugging
135
+ - Full browser DevTools for debugging (F12 is your friend)
120
136
  - Access to DOM, localStorage, fetch, and all browser APIs
137
+ - Watch your tests fail in glorious 1080p
121
138
 
122
- ### Headless Browser Mode
139
+ ### 🤖 Headless browser mode
123
140
 
124
- **Best for:** CI/CD and automated testing
141
+ **Best for:** CI/CD and automated testing (robots don't need screens)
125
142
 
126
143
  ```bash
127
144
  # Chrome (default)
@@ -130,27 +147,29 @@ npx testify --headless
130
147
  # Firefox
131
148
  npx testify --headless --browser firefox
132
149
 
133
- # Safari/WebKit
150
+ # Safari/WebKit (for the brave)
134
151
  npx testify --headless --browser webkit
135
152
  ```
136
153
 
137
- - Runs real browser without UI
154
+ - Runs real browser without UI (like a browser in witness protection)
138
155
  - Full browser API support
139
156
  - Console output with test results
140
157
  - Excellent for cross-browser testing
158
+ - No awkward eye contact with DevTools
141
159
 
142
- ### Node.js Mode
160
+ ### Node.js mode
143
161
 
144
- **Best for:** Fast unit testing
162
+ **Best for:** Fast unit testing (when you just want to go home early)
145
163
 
146
164
  ```bash
147
165
  npx testify --headless --browser node
148
166
  ```
149
167
 
150
- - Fastest execution (no browser startup overhead)
168
+ - Fastest execution (no browser startup overhead—just pure speed)
151
169
  - Limited to Node.js APIs only
152
- - Perfect for pure TypeScript logic
170
+ - Perfect for pure TypeScript logic that doesn't need a browser's emotional support
153
171
  - No DOM or browser-specific APIs
172
+ - Your tests run so fast you'll think they're not even running (they are, we promise)
154
173
 
155
174
  **Suppress console output:**
156
175
  ```bash
@@ -167,25 +186,26 @@ npx testify --headless --browser node --quiet
167
186
  TS_TEST_RUNNER_SUPPRESS_CONSOLE_LOGS=1 npx testify --headless --browser node
168
187
  ```
169
188
 
170
- ### Watch Mode
189
+ ### 🔥 Watch mode
171
190
 
172
- **Best for:** Rapid development iteration
191
+ **Best for:** Rapid development iteration (and existential dread watching tests fail in real-time)
173
192
 
174
193
  ```bash
175
194
  npx testify --watch
176
195
  ```
177
196
 
178
- - Hot Module Reload for instant feedback
179
- - Watches source and test files for changes
197
+ - Hot Module Reload for instant feedback (faster than your morning coffee)
198
+ - Watches source and test files for changes (like a very attentive guard dog)
180
199
  - Automatically re-runs affected tests
181
200
  - Only works in headed browser mode
182
201
  - WebSocket-based synchronization
202
+ - Warning: May cause productivity addiction
183
203
 
184
- **Important:** Watch mode cannot be combined with `--headless` or `--coverage`.
204
+ **Important:** Watch mode cannot be combined with `--headless` or `--coverage`. (We tried. The universe said no.)
185
205
 
186
206
  ---
187
207
 
188
- ## Code Coverage
208
+ ## 📊 Code coverage
189
209
 
190
210
  Enable Istanbul code coverage with the `--coverage` flag:
191
211
 
@@ -207,122 +227,9 @@ npx testify --coverage
207
227
 
208
228
  ---
209
229
 
210
- ## Configuration Reference
211
-
212
- ### Configuration File: `testify.json`
230
+ ## 🧪 Environment-specific testing
213
231
 
214
- ```json
215
- {
216
- // Source and test directories
217
- "srcDirs": ["./src/lib"],
218
- "testDirs": ["./src/tests"],
219
- "exclude": ["**/node_modules/**", "**/.git/**"],
220
-
221
- // Build output
222
- "outDir": "./dist/.vite-jasmine-build",
223
- "preserveOutputs": false,
224
-
225
- // Execution settings
226
- "browser": "chrome",
227
- "headless": false,
228
- "port": 8888,
229
- "coverage": false,
230
- "watch": false,
231
- "suppressConsoleLogs": false,
232
-
233
- // TypeScript configuration
234
- "tsconfig": "tsconfig.json",
235
-
236
- // Jasmine configuration
237
- "jasmineConfig": {
238
- "env": {
239
- "random": true,
240
- "seed": 0,
241
- "timeout": 120000,
242
- "stopSpecOnExpectationFailure": false
243
- }
244
- },
245
-
246
- // HTML page customization
247
- "htmlOptions": {
248
- "title": "My Project Tests"
249
- },
250
-
251
- // Vite build options
252
- "viteBuildOptions": {
253
- "target": "es2022",
254
- "sourcemap": true,
255
- "minify": false
256
- }
257
- }
258
- ```
259
-
260
- ### Configuration Options
261
-
262
- | Option | Type | Default | Description |
263
- |--------|------|---------|-------------|
264
- | `srcDirs` | `string[]` | `["./src"]` | Source code directories |
265
- | `testDirs` | `string[]` | `["./tests"]` | Test file directories |
266
- | `exclude` | `string[]` | `["**/node_modules/**"]` | Patterns to exclude |
267
- | `outDir` | `string` | `"./dist/.vite-jasmine-build"` | Build output directory |
268
- | `browser` | `string` | `"chrome"` | Browser to use: `chrome`, `firefox`, `webkit`, `node` |
269
- | `headless` | `boolean` | `false` | Run in headless mode |
270
- | `port` | `number` | `8888` | Development server port |
271
- | `coverage` | `boolean` | `false` | Enable code coverage |
272
- | `watch` | `boolean` | `false` | Enable watch mode with HMR |
273
- | `suppressConsoleLogs` | `boolean` | `false` | Hide spec-level console output in Node mode |
274
- | `preserveOutputs` | `boolean` | `false` | Skip regenerating outputs when they exist |
275
-
276
- ---
277
-
278
- ## Command Line Reference
279
-
280
- ### Basic Commands
281
-
282
- | Command | Description |
283
- |---------|-------------|
284
- | `npx testify` | Run in browser (development mode) |
285
- | `npx testify init` | Create configuration file |
286
- | `npx testify --help` | Show help message |
287
-
288
- ### Execution Flags
289
-
290
- | Flag | Description |
291
- |------|-------------|
292
- | `--headless` | Run in headless mode |
293
- | `--browser <n>` | Choose browser: `chrome`, `firefox`, `webkit`, `node` |
294
- | `--watch` | Enable watch mode with HMR |
295
- | `--coverage` | Generate code coverage reports |
296
- | `--seed <number>` | Set randomization seed |
297
- | `--silent` / `--quiet` | Suppress console logs (Node mode only) |
298
- | `--preserve` | Skip regenerating outputs when they exist |
299
- | `--config <path>` | Use custom config file |
300
-
301
- ### Examples
302
-
303
- ```bash
304
- # Development workflow
305
- npx testify --watch
306
-
307
- # CI/CD pipeline
308
- npx testify --headless --coverage
309
-
310
- # Cross-browser testing
311
- npx testify --headless --browser firefox
312
- npx testify --headless --browser webkit
313
-
314
- # Deterministic test order
315
- npx testify --seed 12345
316
-
317
- # Fast unit tests with clean console
318
- npx testify --headless --browser node --silent
319
- ```
320
-
321
- ---
322
-
323
- ## Environment-Specific Testing
324
-
325
- ### Browser-Only Tests
232
+ ### Browser-only tests
326
233
 
327
234
  ```typescript
328
235
  describe('Browser APIs', () => {
@@ -350,7 +257,7 @@ describe('Browser APIs', () => {
350
257
  });
351
258
  ```
352
259
 
353
- ### Node.js-Only Tests
260
+ ### Node.js-only tests
354
261
 
355
262
  ```typescript
356
263
  describe('Node.js APIs', () => {
@@ -373,7 +280,7 @@ describe('Node.js APIs', () => {
373
280
  });
374
281
  ```
375
282
 
376
- ### Cross-Environment Tests
283
+ ### Cross-environment tests
377
284
 
378
285
  ```typescript
379
286
  describe('Universal Code', () => {
@@ -393,7 +300,7 @@ describe('Universal Code', () => {
393
300
 
394
301
  ---
395
302
 
396
- ## Single Spec Runner (jasmine)
303
+ ## 🐛 Single spec runner (jasmine)
397
304
 
398
305
  Run a single spec file in Node.js using `jasmine-core`:
399
306
 
@@ -407,7 +314,7 @@ node --loader @epikodelabs/testify/esm-loader.mjs \
407
314
  --spec ./tests/example.spec.ts
408
315
  ```
409
316
 
410
- ### VS Code Debug Configuration
317
+ ### VS Code debug configuration
411
318
 
412
319
  Create or update `.vscode/launch.json`:
413
320
 
@@ -438,7 +345,7 @@ Or manually add this configuration:
438
345
 
439
346
  **Important:** Do not point at `node_modules/.bin/jasmine` (shell shim). Always use the full path to the actual JS file.
440
347
 
441
- ### jasmine Options
348
+ ### jasmine options
442
349
 
443
350
  ```bash
444
351
  npx jasmine --spec <path> # Path to spec file
@@ -451,9 +358,9 @@ npx jasmine init # Create VS Code debug config
451
358
 
452
359
  ---
453
360
 
454
- ## CI/CD Integration
361
+ ## 🚀 CI/CD integration
455
362
 
456
- ### GitHub Actions Example
363
+ ### GitHub Actions example
457
364
 
458
365
  ```yaml
459
366
  name: Tests
@@ -490,131 +397,181 @@ jobs:
490
397
  files: ./coverage/lcov.info
491
398
  ```
492
399
 
493
- ### Performance Comparison
400
+ ### Performance comparison
494
401
 
495
402
  | Environment | Speed | Browser APIs | Use Case |
496
403
  |-------------|-------|-------------|----------|
497
- | Node.js | ⚡ Fastest | ❌ None | Unit tests, pure logic |
498
- | Headless Chrome | 🐌 Medium | ✅ Full | Integration tests, DOM |
499
- | Headless Firefox | 🐌 Medium | ✅ Full | Cross-browser testing |
500
- | Browser (headed) | 🐌 Slowest | ✅ Full + DevTools | Development, debugging |
404
+ | Node.js | ⚡ Fastest (blink and you'll miss it) | ❌ None | Unit tests, pure logic |
405
+ | Headless Chrome | 🐌 Medium (coffee break pace) | ✅ Full | Integration tests, DOM |
406
+ | Headless Firefox | 🐌 Medium (also coffee break pace) | ✅ Full | Cross-browser testing |
407
+ | Browser (headed) | 🐌 Slowest (full meal pace) | ✅ Full + DevTools | Development, debugging |
501
408
 
502
409
  ---
503
410
 
504
- ## Project Structure
411
+ ## ⚖️ testify vs other test runners
505
412
 
506
- The test runner expects this structure (all paths are configurable):
413
+ | Feature | testify | Jest | Vitest | Karma |
414
+ |---------|---------|------|--------|-------|
415
+ | Real browser testing | ✅ | ❌ | ❌ | ✅ |
416
+ | Node.js execution | ✅ | ✅ | ✅ | ❌ |
417
+ | Hot Module Reload | ✅ | ✅ | ✅ | ❌ |
418
+ | TypeScript support | ✅ | ✅ | ✅ | ⚠️ Plugin |
419
+ | Code coverage | ✅ | ✅ | ✅ | ✅ |
420
+ | Setup complexity | Low | Medium | Low | High |
421
+ | Jasmine framework | ✅ | ❌ | ❌ | ✅ |
422
+ | Active maintenance | ✅ | ✅ | ✅ | ⚠️ Limited |
423
+ | Name sounds like courtroom drama | ✅ | ❌ | ❌ | ⚠️ Kinda |
507
424
 
508
- ```
509
- your-project/
510
- ├── src/
511
- │ ├── lib/ # Source code
512
- │ │ ├── calculator.ts
513
- │ │ └── utils.ts
514
- │ └── tests/ # Test files
515
- │ ├── calculator.spec.ts
516
- │ └── utils.spec.ts
517
- ├── dist/
518
- │ └── .vite-jasmine-build/ # Compiled output (auto-generated)
519
- │ ├── index.html
520
- │ ├── test-runner.js
521
- │ └── *.js
522
- ├── coverage/ # Coverage reports (auto-generated)
523
- │ ├── index.html
524
- │ └── lcov.info
525
- ├── testify.json # Configuration file
526
- └── tsconfig.json # TypeScript configuration
527
- ```
425
+ **Why choose testify:**
426
+ - **vs Jest:** Better real browser testing support, actual browser environments (and our name is easier to spell)
427
+ - **vs Vitest:** Established Jasmine ecosystem, simpler for existing Jasmine users (also, we tested our name—it works)
428
+ - **vs Karma:** Modern tooling, TypeScript-first, simpler setup, active development (and way less karmic baggage)
528
429
 
529
430
  ---
530
431
 
531
- ## Troubleshooting
532
-
533
- ### Browser Not Found
534
-
535
- ```bash
536
- # Install all browsers
537
- npx playwright install
538
-
539
- # Or install specific browser
540
- npx playwright install chrome
541
- npx playwright install firefox
542
- npx playwright install webkit
543
- ```
544
-
545
- ### Port Already in Use
432
+ ## 🔧 Configuration reference
546
433
 
547
- Change the port in `testify.json`:
434
+ ### Configuration file: `testify.json`
548
435
 
549
436
  ```json
550
437
  {
551
- "port": 3000
438
+ // Source and test directories
439
+ "srcDirs": ["./src/lib"],
440
+ "testDirs": ["./src/tests"],
441
+ "exclude": ["**/node_modules/**", "**/.git/**"],
442
+
443
+ // Build output
444
+ "outDir": "./dist/.vite-jasmine-build",
445
+ "preserveOutputs": false,
446
+
447
+ // Execution settings
448
+ "browser": "chrome",
449
+ "headless": false,
450
+ "port": 8888,
451
+ "coverage": false,
452
+ "watch": false,
453
+ "suppressConsoleLogs": false,
454
+
455
+ // TypeScript configuration
456
+ "tsconfig": "tsconfig.json",
457
+
458
+ // Jasmine configuration
459
+ "jasmineConfig": {
460
+ "env": {
461
+ "random": true,
462
+ "seed": 0,
463
+ "timeout": 120000,
464
+ "stopSpecOnExpectationFailure": false
465
+ }
466
+ },
467
+
468
+ // HTML page customization
469
+ "htmlOptions": {
470
+ "title": "My Project Tests"
471
+ },
472
+
473
+ // Vite build options
474
+ "viteBuildOptions": {
475
+ "target": "es2022",
476
+ "sourcemap": true,
477
+ "minify": false
478
+ }
552
479
  }
553
480
  ```
554
481
 
555
- Or use a different port via command line:
482
+ ### Configuration options
556
483
 
557
- ```bash
558
- # Note: Currently requires config file change
559
- # CLI port override coming in future version
560
- ```
484
+ | Option | Type | Default | Description |
485
+ |--------|------|---------|-------------|
486
+ | `srcDirs` | `string[]` | `["./src"]` | Source code directories |
487
+ | `testDirs` | `string[]` | `["./tests"]` | Test file directories |
488
+ | `exclude` | `string[]` | `["**/node_modules/**"]` | Patterns to exclude |
489
+ | `outDir` | `string` | `"./dist/.vite-jasmine-build"` | Build output directory |
490
+ | `browser` | `string` | `"chrome"` | Browser to use: `chrome`, `firefox`, `webkit`, `node` |
491
+ | `headless` | `boolean` | `false` | Run in headless mode |
492
+ | `port` | `number` | `8888` | Development server port |
493
+ | `coverage` | `boolean` | `false` | Enable code coverage |
494
+ | `watch` | `boolean` | `false` | Enable watch mode with HMR |
495
+ | `suppressConsoleLogs` | `boolean` | `false` | Hide spec-level console output in Node mode |
496
+ | `preserveOutputs` | `boolean` | `false` | Skip regenerating outputs when they exist |
497
+
498
+ ---
499
+
500
+ ## 📖 Command line reference
501
+
502
+ ### Basic commands
561
503
 
562
- ### No Tests Found
504
+ | Command | Description |
505
+ |---------|-------------|
506
+ | `npx testify` | Run in browser (development mode) |
507
+ | `npx testify init` | Create configuration file |
508
+ | `npx testify --help` | Show help message |
563
509
 
564
- Verify:
565
- - Test files are in the `testDirs` location
566
- - Files have `.spec.ts` or `.spec.js` extension
567
- - Tests use proper Jasmine syntax (`describe`, `it`, `expect`)
568
- - Directories are not in the `exclude` list
510
+ ### Execution flags
511
+
512
+ | Flag | Description |
513
+ |------|-------------|
514
+ | `--headless` | Run in headless mode |
515
+ | `--browser <n>` | Choose browser: `chrome`, `firefox`, `webkit`, `node` |
516
+ | `--watch` | Enable watch mode with HMR |
517
+ | `--coverage` | Generate code coverage reports |
518
+ | `--seed <number>` | Set randomization seed |
519
+ | `--silent` / `--quiet` | Suppress console logs (Node mode only) |
520
+ | `--preserve` | Skip regenerating outputs when they exist |
521
+ | `--config <path>` | Use custom config file |
569
522
 
570
- ### TypeScript Compilation Errors
523
+ ### Examples
571
524
 
572
- 1. Check your `tsconfig.json` matches your project structure
573
- 2. Ensure `tsconfig` path in `testify.json` is correct
574
- 3. Verify path aliases are properly configured
575
- 4. Check that all dependencies are installed
525
+ ```bash
526
+ # Development workflow
527
+ npx testify --watch
576
528
 
577
- ### Watch Mode Not Working
529
+ # CI/CD pipeline
530
+ npx testify --headless --coverage
578
531
 
579
- Remember:
580
- - Watch mode only works in headed browser mode
581
- - Cannot use with `--headless` flag
582
- - Cannot use with `--coverage` flag
583
- - Cannot use with `--browser node`
532
+ # Cross-browser testing
533
+ npx testify --headless --browser firefox
534
+ npx testify --headless --browser webkit
584
535
 
585
- ### Coverage Reports Missing
536
+ # Deterministic test order
537
+ npx testify --seed 12345
586
538
 
587
- Ensure:
588
- - `--coverage` flag is used
589
- - Tests complete successfully
590
- - Output directory (`coverage/`) has write permissions
591
- - Not using `--watch` mode (coverage disabled in watch mode)
539
+ # Fast unit tests with clean console
540
+ npx testify --headless --browser node --silent
541
+ ```
592
542
 
593
543
  ---
594
544
 
595
- ## Comparison with Other Test Runners
545
+ ## 📁 Project structure
596
546
 
597
- | Feature | testify | Jest | Vitest | Karma |
598
- |---------|---------------|------|--------|-------|
599
- | Real browser testing | ✅ | ❌ | ❌ | ✅ |
600
- | Node.js execution | ✅ | ✅ | ✅ | ❌ |
601
- | Hot Module Reload | ✅ | ✅ | ✅ | ❌ |
602
- | TypeScript support | ✅ | ✅ | ✅ | ⚠️ Plugin |
603
- | Code coverage | ✅ | ✅ | ✅ | ✅ |
604
- | Setup complexity | Low | Medium | Low | High |
605
- | Jasmine framework | ✅ | ❌ | ❌ | ✅ |
606
- | Active maintenance | ✅ | ✅ | ✅ | ⚠️ Limited |
547
+ The test runner expects this structure (all paths are configurable):
607
548
 
608
- **Why choose testify:**
609
- - **vs Jest:** Better real browser testing support, actual browser environments
610
- - **vs Vitest:** Established Jasmine ecosystem, simpler for existing Jasmine users
611
- - **vs Karma:** Modern tooling, TypeScript-first, simpler setup, active development
549
+ ```
550
+ your-project/
551
+ ├── src/
552
+ │ ├── lib/ # Source code
553
+ │ │ ├── calculator.ts
554
+ │ │ └── utils.ts
555
+ │ └── tests/ # Test files
556
+ │ ├── calculator.spec.ts
557
+ │ └── utils.spec.ts
558
+ ├── dist/
559
+ │ └── .vite-jasmine-build/ # Compiled output (auto-generated)
560
+ │ ├── index.html
561
+ │ ├── test-runner.js
562
+ │ └── *.js
563
+ ├── coverage/ # Coverage reports (auto-generated)
564
+ │ ├── index.html
565
+ │ └── lcov.info
566
+ ├── testify.json # Configuration file
567
+ └── tsconfig.json # TypeScript configuration
568
+ ```
612
569
 
613
570
  ---
614
571
 
615
- ## Advanced Configuration
572
+ ## 🔧 Advanced configuration
616
573
 
617
- ### Custom Vite Configuration
574
+ ### Custom Vite configuration
618
575
 
619
576
  You can extend the Vite configuration in `testify.json`:
620
577
 
@@ -631,7 +588,7 @@ You can extend the Vite configuration in `testify.json`:
631
588
  }
632
589
  ```
633
590
 
634
- ### TypeScript Path Mapping
591
+ ### TypeScript path mapping
635
592
 
636
593
  Path aliases from `tsconfig.json` are automatically resolved:
637
594
 
@@ -648,7 +605,7 @@ Path aliases from `tsconfig.json` are automatically resolved:
648
605
  }
649
606
  ```
650
607
 
651
- ### Multiple Source Directories
608
+ ### Multiple source directories
652
609
 
653
610
  ```json
654
611
  {
@@ -657,7 +614,7 @@ Path aliases from `tsconfig.json` are automatically resolved:
657
614
  }
658
615
  ```
659
616
 
660
- ### Exclude Patterns
617
+ ### Exclude patterns
661
618
 
662
619
  ```json
663
620
  {
@@ -673,14 +630,90 @@ Path aliases from `tsconfig.json` are automatically resolved:
673
630
 
674
631
  ---
675
632
 
676
- ## License
633
+ ## ❓ Troubleshooting
677
634
 
678
- MIT © 2025
635
+ ### Browser not found
636
+
637
+ Did you forget to invite the browsers to the party?
638
+
639
+ ```bash
640
+ # Install all browsers (the whole squad)
641
+ npx playwright install
642
+
643
+ # Or install specific browser (selective guest list)
644
+ npx playwright install chrome
645
+ npx playwright install firefox
646
+ npx playwright install webkit
647
+ ```
648
+
649
+ ### Port already in use
650
+
651
+ Someone's camping on port 8888? Rude. Change the port in `testify.json`:
652
+
653
+ ```json
654
+ {
655
+ "port": 3000
656
+ }
657
+ ```
658
+
659
+ Or use a different port via command line:
660
+
661
+ ```bash
662
+ # Note: Currently requires config file change
663
+ # CLI port override coming in future version
664
+ # (We're working on it, okay? Rome wasn't built in a day)
665
+ ```
666
+
667
+ ### No tests found
668
+
669
+ testify is looking for tests like a detective at a crime scene. Make sure:
670
+ - Test files are in the `testDirs` location (it's not a treasure hunt)
671
+ - Files have `.spec.ts` or `.spec.js` extension (naming conventions matter, people!)
672
+ - Tests use proper Jasmine syntax (`describe`, `it`, `expect`) (no, `console.log` is not a test)
673
+ - Directories are not in the `exclude` list (check if you accidentally ghosted your tests)
674
+
675
+ ### TypeScript compilation errors
676
+
677
+ TypeScript is being picky again? Let's troubleshoot:
678
+
679
+ 1. Check your `tsconfig.json` matches your project structure (did you move files around and forget to tell TypeScript?)
680
+ 2. Ensure `tsconfig` path in `testify.json` is correct (typos happen to the best of us)
681
+ 3. Verify path aliases are properly configured (@ symbols need love too)
682
+ 4. Check that all dependencies are installed (did you `npm install`? Did you *really*?)
683
+
684
+ ### Watch mode not working
685
+
686
+ Watch mode is like that one friend who only shows up under specific conditions:
687
+ - Watch mode only works in headed browser mode (it likes to see what's happening)
688
+ - Cannot use with `--headless` flag (it's shy without a UI)
689
+ - Cannot use with `--coverage` flag (it can't multitask)
690
+ - Cannot use with `--browser node` (needs a real browser, not a pretend one)
691
+
692
+ ### Coverage reports missing
693
+
694
+ Coverage reports playing hide and seek? Make sure:
695
+ - `--coverage` flag is used (it's not going to turn on itself)
696
+ - Tests complete successfully (failed tests don't generate coverage, obviously)
697
+ - Output directory (`coverage/`) has write permissions (is it read-only? That's a paddlin')
698
+ - Not using `--watch` mode (coverage and watch mode are like oil and water—they don't mix)
699
+
700
+ ---
701
+
702
+ ## 📜 License
703
+
704
+ MIT © 2026
679
705
 
680
706
  ---
681
707
 
682
- ## Support
708
+ ## 🤝 Support
683
709
 
684
710
  - **Issues:** [GitHub Issues](https://github.com/epikodelabs/testify/issues)
685
711
  - **Documentation:** [GitHub Wiki](https://github.com/epikodelabs/testify/wiki)
686
- - **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
712
+
713
+ ---
714
+
715
+ <p align="center">
716
+ <strong>Get started</strong><br>
717
+ <a href="https://www.npmjs.com/package/@epikodelabs/testify">Install from NPM</a> •
718
+ <a href="https://github.com/epikodelabs/testify">View on GitHub</a>
719
+ </p>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@epikodelabs/testify",
3
- "version": "1.0.16",
3
+ "version": "1.0.18",
4
4
  "description": "Serve and run your Jasmine specs in a browser",
5
5
  "type": "module",
6
6
  "bin": {