fix(readme): Update README: Revamp structure for features, installation, and examples
This commit is contained in:
parent
d0c87050c0
commit
d6959c13e9
@ -1,5 +1,12 @@
|
||||
# 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)
|
||||
Add explicit fail method to the Tap class for better test failure handling
|
||||
|
||||
|
||||
190
readme.md
190
readme.md
@ -2,23 +2,39 @@
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
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**
|
||||
|
||||
@ -28,11 +44,9 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
|
||||
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
|
||||
import { tap, expect } from '@push.rocks/tapbundle';
|
||||
|
||||
tap.test('Initial test succeeds', async () => {
|
||||
return expect(true).toBeTrue();
|
||||
});
|
||||
@ -40,23 +54,14 @@ To begin using `tapbundle`, ensure that your TypeScript project is configured fo
|
||||
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**
|
||||
|
||||
You can define tests using the `tap.test` method, where you provide a description and an asynchronous function:
|
||||
|
||||
```typescript
|
||||
tap.test('basic arithmetic test', async () => {
|
||||
expect(1 + 1).toEqual(2);
|
||||
});
|
||||
```
|
||||
|
||||
**Async Tests Handling**
|
||||
|
||||
Use `expectAsync` for promises or async operations:
|
||||
|
||||
```typescript
|
||||
// Async Tests
|
||||
tap.test('async operation test', async () => {
|
||||
const fetchData = async () => Promise.resolve('data');
|
||||
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**
|
||||
|
||||
`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:
|
||||
|
||||
```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:
|
||||
4. **Execution Control**
|
||||
|
||||
```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 () => {
|
||||
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 () => {
|
||||
const { key, cert } = await tapNodeTools.createHttpsCert('localhost');
|
||||
expect(key).toInclude('-----BEGIN RSA PRIVATE KEY-----');
|
||||
expect(cert).toInclude('-----BEGIN CERTIFICATE-----');
|
||||
});
|
||||
```
|
||||
|
||||
6. **Working with Environment Variables**
|
||||
|
||||
Leverage the power of dynamic environment management using `qenv`:
|
||||
6. **Environment Variables**
|
||||
|
||||
```typescript
|
||||
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**
|
||||
|
||||
The framework allows for precise control over asynchronous processes, introducing race conditions or coordinated delays:
|
||||
7. **Asynchronous Control**
|
||||
|
||||
```typescript
|
||||
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**
|
||||
|
||||
If your testing involves browser environments, make use of the `webhelpers` utilities, for instance with libraries like Open WC:
|
||||
8. **Web Testing**
|
||||
|
||||
```typescript
|
||||
import { webhelpers } from './webhelpers.js';
|
||||
import { webhelpers } from '@push.rocks/tapbundle';
|
||||
|
||||
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();
|
||||
});
|
||||
```
|
||||
|
||||
9. **Using Webhelpers in Browser**
|
||||
9. **Database and Storage Testing**
|
||||
|
||||
Make the tests more interactive, especially for UI Components:
|
||||
|
||||
```typescript
|
||||
tap.preTask('Setup pre-task for UI test', async () => {
|
||||
console.log('Setting up for UI tests');
|
||||
```typescript
|
||||
tap.test('Smartmongo setup test', async () => {
|
||||
const smartmongo = await tapNodeTools.createSmartmongo();
|
||||
await smartmongo.stop();
|
||||
});
|
||||
|
||||
tap.test('UI test with Web Component', async () => {
|
||||
const myEl = await webhelpers.fixture(webhelpers.html`<div id="myEl">Content</div>`);
|
||||
expect(myEl.id).toBe('myEl');
|
||||
tap.test('Smarts3 setup', async () => {
|
||||
const smarts3 = await tapNodeTools.createSmarts3();
|
||||
console.log('Smarts3 running');
|
||||
await smarts3.stop();
|
||||
});
|
||||
```
|
||||
|
||||
10. **Leveraging Smartmongo and Smarts3**
|
||||
## Best Practices
|
||||
|
||||
Whether you’re working with databases or cloud storage simulations:
|
||||
|
||||
```typescript
|
||||
tap.test('Smartmongo setup test', async () => {
|
||||
const smartmongo = await tapNodeTools.createSmartmongo();
|
||||
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!
|
||||
1. Use descriptive test names that explain the expected behavior
|
||||
2. Leverage pre-tasks for common setup operations
|
||||
3. Use `testParallel` for independent tests that can run concurrently
|
||||
4. Utilize test coordination for dependent tests
|
||||
5. Set appropriate timeouts for async operations
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
|
||||
@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
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.'
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user