push.rocks/tapbundle
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(readme): Update README: Revamp structure for features, installation, and examples

Browse Source
This commit is contained in:
Philipp Kunz 2025-04-02 14:19:49 +00:00
parent d0c87050c0
commit d6959c13e9
3 changed files with 88 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
changelog.md
View File

@ -1,5 +1,12 @@
# Changelog # Changelog
## 2025-04-02 - 5.6.1 - fix(readme)
Update README: Revamp structure for features, installation, and examples
- Reorganized sections to highlight features, installation, core API, and getting started
- Updated code examples for clarity, including Node integration and web testing sections
- Standardized headings and removed extraneous documentation details
## 2025-03-17 - 5.6.0 - feat(tap) ## 2025-03-17 - 5.6.0 - feat(tap)
Add explicit fail method to the Tap class for better test failure handling Add explicit fail method to the Tap class for better test failure handling

190
readme.md
View File

@ -2,23 +2,39 @@
A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer. A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.
## Install ## Features
To install the package, execute: - TAP (Test Anything Protocol) compliant output
- Support for both browser and Node.js environments
- Built-in test coordination and timing measurements
- Parallel and sequential test execution
- Pre-task support for setup operations
- Rich assertion library via `expect`
- Comprehensive Node.js tooling (shell, crypto, MongoDB, S3)
## Installation
```bash ```bash
npm install @push.rocks/tapbundle --save-dev npm install @push.rocks/tapbundle --save-dev
``` ```
This command will add `@push.rocks/tapbundle` to your project's `devDependencies`, ensuring it is only used during development and testing.
## Usage ## Usage
The `@push.rocks/tapbundle` is a versatile testing framework compatible with TAP, designed using TypeScript to facilitate robust and scalable testing of applications, whether you are dealing with unit tests, integration tests, or simply need a streamlined way to automate assertions across your application’s lifecycle. The framework is especially useful if you are already using or planning to use tapbuffer. The `@push.rocks/tapbundle` is a versatile testing framework compatible with TAP, designed using TypeScript to facilitate robust and scalable testing of applications, whether you are dealing with unit tests, integration tests, or simply need a streamlined way to automate assertions across your application's lifecycle. The framework is especially useful if you are already using or planning to use tapbuffer.
**Getting Started** ### Core API
To begin using `tapbundle`, ensure that your TypeScript project is configured for ESM syntax. Here's how you can set it up and start writing your tests: The main test runner is accessed through the `tap` object:
```typescript
tap.test(
description: string, // Test description
testFunction: async (tools?: TapTools) => Promise<any>, // Test implementation
modeArg: 'normal' | 'only' | 'skip' = 'normal' // Execution mode
): TapTest
```
### Getting Started
1. **Basic Setup** 1. **Basic Setup**
@ -28,11 +44,9 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
import { tap, expect, expectAsync } from '@push.rocks/tapbundle'; import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
``` ```
Start with a simple test to ensure everything is set up correctly: Start with a simple test:
```typescript ```typescript
import { tap, expect } from '@push.rocks/tapbundle';
tap.test('Initial test succeeds', async () => { tap.test('Initial test succeeds', async () => {
return expect(true).toBeTrue(); return expect(true).toBeTrue();
}); });
@ -40,23 +54,14 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
tap.start(); tap.start();
``` ```
The above code establishes a basic test environment, using the `tap` instance to manage execution flow and `expect` for assertions.
2. **Defining and Organizing Tests** 2. **Defining and Organizing Tests**
You can define tests using the `tap.test` method, where you provide a description and an asynchronous function:
```typescript ```typescript
tap.test('basic arithmetic test', async () => { tap.test('basic arithmetic test', async () => {
expect(1 + 1).toEqual(2); expect(1 + 1).toEqual(2);
}); });
```
**Async Tests Handling** // Async Tests
Use `expectAsync` for promises or async operations:
```typescript
tap.test('async operation test', async () => { tap.test('async operation test', async () => {
const fetchData = async () => Promise.resolve('data'); const fetchData = async () => Promise.resolve('data');
await expectAsync(fetchData()).toBeResolved(); await expectAsync(fetchData()).toBeResolved();
@ -65,62 +70,43 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
3. **Tools for Advanced Testing** 3. **Tools for Advanced Testing**
`tapbundle` equips you with tools for sophisticated test scenarios: ```typescript
// Delay and Timing
tap.test('test with delay', async (tools) => {
await tools.delayFor(500); // waits for 500ms
expect(true).toBeTrue();
});
- **Delay and Timing** // Custom Pre Tasks
tap.preTask('initialize environment', async () => {
console.log('Setting up preconditions');
});
```
Integrated delay methods are handy for simulating timeouts and waiting states: 4. **Execution Control**
```typescript
tap.test('test with delay', async (tools) => {
await tools.delayFor(500); // waits for 500ms
expect(true).toBeTrue();
});
```
- **Custom Pre Tasks**
Set up tasks to run before your test suite begins. This can be setup operations like initializing databases:
```typescript
tap.preTask('initialize environment', async () => {
console.log('Setting up preconditions');
});
```
4. **Execution and Control**
- **Running Tests**
Call `tap.start()` to execute your suite. Handle specific conditions using `.skip` or `.only`:
```typescript
tap.skip.test('skip this test', async () => {
// This test will be ignored
});
tap.only.test('run this test exclusively', async () => {
// Only this test will run among defined tests
});
```
- **Handling Errors and Debugging**
Make use of `consolecolor` to make outputs readable:
```typescript
tap.test('test with colored output', async (tools) => {
const message = await tools.coloredString('Test Passed!', 'green');
console.log(message);
});
```
5. **Integration with Node Tools**
For operations involving the shell or environment-specific setups, use Node tools provided:
```typescript ```typescript
import { tapNodeTools } from './ts_node/index.js'; // Skip tests
tap.skip.test('skip this test', async () => {
// This test will be ignored
});
// Exclusive tests
tap.only.test('run this test exclusively', async () => {
// Only this test will run
});
// Colored output
tap.test('test with colored output', async (tools) => {
const message = await tools.coloredString('Test Passed!', 'green');
console.log(message);
});
```
5. **Node.js Integration**
```typescript
import { tapNodeTools } from '@push.rocks/tapbundle/node';
tap.test('execute shell command', async () => { tap.test('execute shell command', async () => {
const result = await tapNodeTools.runCommand('ls -la'); const result = await tapNodeTools.runCommand('ls -la');
@ -130,13 +116,10 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
tap.test('create HTTPS certificate', async () => { tap.test('create HTTPS certificate', async () => {
const { key, cert } = await tapNodeTools.createHttpsCert('localhost'); const { key, cert } = await tapNodeTools.createHttpsCert('localhost');
expect(key).toInclude('-----BEGIN RSA PRIVATE KEY-----'); expect(key).toInclude('-----BEGIN RSA PRIVATE KEY-----');
expect(cert).toInclude('-----BEGIN CERTIFICATE-----');
}); });
``` ```
6. **Working with Environment Variables** 6. **Environment Variables**
Leverage the power of dynamic environment management using `qenv`:
```typescript ```typescript
tap.test('use environment variable', async (tools) => { tap.test('use environment variable', async (tools) => {
@ -145,9 +128,7 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
}); });
``` ```
7. **Managing Asynchronous Behavior** 7. **Asynchronous Control**
The framework allows for precise control over asynchronous processes, introducing race conditions or coordinated delays:
```typescript ```typescript
tap.test('controlled async scenario', async (tools) => { tap.test('controlled async scenario', async (tools) => {
@ -158,52 +139,41 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
}); });
``` ```
8. **Web Testing Utilities** 8. **Web Testing**
If your testing involves browser environments, make use of the `webhelpers` utilities, for instance with libraries like Open WC:
```typescript ```typescript
import { webhelpers } from './webhelpers.js'; import { webhelpers } from '@push.rocks/tapbundle';
tap.test('web component test', async () => { tap.test('web component test', async () => {
const element = await webhelpers.fixture(webhelpers.html`<my-element></my-element>`); const element = await webhelpers.fixture(
webhelpers.html`<my-element></my-element>`
);
expect(element.shadowRoot.querySelector('div')).toBeDefined(); expect(element.shadowRoot.querySelector('div')).toBeDefined();
}); });
``` ```
9. **Using Webhelpers in Browser** 9. **Database and Storage Testing**
Make the tests more interactive, especially for UI Components: ```typescript
tap.test('Smartmongo setup test', async () => {
```typescript const smartmongo = await tapNodeTools.createSmartmongo();
tap.preTask('Setup pre-task for UI test', async () => { await smartmongo.stop();
console.log('Setting up for UI tests');
}); });
tap.test('UI test with Web Component', async () => { tap.test('Smarts3 setup', async () => {
const myEl = await webhelpers.fixture(webhelpers.html`<div id="myEl">Content</div>`); const smarts3 = await tapNodeTools.createSmarts3();
expect(myEl.id).toBe('myEl'); console.log('Smarts3 running');
await smarts3.stop();
}); });
``` ```
10. **Leveraging Smartmongo and Smarts3** ## Best Practices
Whether you’re working with databases or cloud storage simulations: 1. Use descriptive test names that explain the expected behavior
2. Leverage pre-tasks for common setup operations
```typescript 3. Use `testParallel` for independent tests that can run concurrently
tap.test('Smartmongo setup test', async () => { 4. Utilize test coordination for dependent tests
const smartmongo = await tapNodeTools.createSmartmongo(); 5. Set appropriate timeouts for async operations
await smartmongo.stop();
});
tap.test('Smarts3 setup', async () => {
const smarts3 = await tapNodeTools.createSmarts3();
console.log('Smarts3 running');
await smarts3.stop();
});
```
Integrating `@push.rocks/tapbundle` streamlines your test management in complex projects. With these tools, intricate scenarios from unit tests to more elaborate integrated environments become easier to handle, providing a structured flow to achieve reliable testing outcomes. Happy testing!
## License and Legal Information ## License and Legal Information

2
ts/00_commitinfo_data.ts
View File

@ -3,6 +3,6 @@
*/ */
export const commitinfo = { export const commitinfo = {
name: '@push.rocks/tapbundle', name: '@push.rocks/tapbundle',
version: '5.6.0', version: '5.6.1',
description: 'A comprehensive testing automation library that provides a wide range of utilities and tools for TAP (Test Anything Protocol) based testing, especially suitable for projects using tapbuffer.' description: 'A comprehensive testing automation library that provides a wide range of utilities and tools for TAP (Test Anything Protocol) based testing, especially suitable for projects using tapbuffer.'
} }