62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# Architecture Overview
|
||
|
||
## Project Structure
|
||
|
||
This project integrates tstest with tapbundle through a modular architecture:
|
||
|
||
1. **tstest** (`/ts/`) - The test runner that discovers and executes test files
|
||
2. **tapbundle** (`/ts_tapbundle/`) - The TAP testing framework for writing tests
|
||
3. **tapbundle_node** (`/ts_tapbundle_node/`) - Node.js-specific testing utilities
|
||
|
||
## How Components Work Together
|
||
|
||
### Test Execution Flow
|
||
|
||
1. **CLI Entry Point** (`cli.js` ’ `cli.ts.js` ’ `cli.child.ts`)
|
||
- The CLI uses tsx to run TypeScript files directly
|
||
- Accepts glob patterns to find test files
|
||
- Supports options like `--verbose`, `--quiet`, `--web`
|
||
|
||
2. **Test Discovery**
|
||
- tstest scans for test files matching the provided pattern
|
||
- Defaults to `test/**/*.ts` when no pattern is specified
|
||
- Supports both file and directory modes
|
||
|
||
3. **Test Runner**
|
||
- Each test file imports `tap` and `expect` from tapbundle
|
||
- Tests are written using `tap.test()` with async functions
|
||
- Browser tests are compiled with esbuild and run in Chromium via Puppeteer
|
||
|
||
### Key Integration Points
|
||
|
||
1. **Import Structure**
|
||
- Test files import from local tapbundle: `import { tap, expect } from '../../ts_tapbundle/index.js'`
|
||
- Node-specific tests also import from tapbundle_node: `import { tapNodeTools } from '../../ts_tapbundle_node/index.js'`
|
||
|
||
2. **WebHelpers**
|
||
- Browser tests can use webhelpers for DOM manipulation
|
||
- `webhelpers.html` - Template literal for creating HTML strings
|
||
- `webhelpers.fixture` - Creates DOM elements from HTML strings
|
||
- Automatically detects browser environment and only enables in browser context
|
||
|
||
3. **Build System**
|
||
- Uses `tsbuild tsfolders` to compile TypeScript
|
||
- Maintains separate output directories: `/dist_ts/`, `/dist_ts_tapbundle/`, `/dist_ts_tapbundle_node/`
|
||
- Compilation order is resolved automatically based on dependencies
|
||
|
||
### Test Scripts
|
||
|
||
The package.json defines several test scripts:
|
||
- `test` - Builds and runs all tests (tapbundle and tstest)
|
||
- `test:tapbundle` - Runs tapbundle framework tests
|
||
- `test:tstest` - Runs tstest's own tests
|
||
- Both support `:verbose` variants for detailed output
|
||
|
||
### Environment Detection
|
||
|
||
The framework automatically detects the runtime environment:
|
||
- Node.js tests run directly via tsx
|
||
- Browser tests are compiled and served via a local server
|
||
- WebHelpers are only enabled in browser environment
|
||
|
||
This architecture allows for seamless testing across both Node.js and browser environments while maintaining a clean separation of concerns. |