From d6959c13e9f6a7d105f0eb366543cdd8fdff3e67 Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Wed, 2 Apr 2025 14:19:49 +0000 Subject: [PATCH] fix(readme): Update README: Revamp structure for features, installation, and examples --- changelog.md | 7 ++ readme.md | 190 +++++++++++++++++---------------------- ts/00_commitinfo_data.ts | 2 +- 3 files changed, 88 insertions(+), 111 deletions(-) diff --git a/changelog.md b/changelog.md index db488f7..276b8f6 100644 --- a/changelog.md +++ b/changelog.md @@ -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 diff --git a/readme.md b/readme.md index 30520f7..dac9790 100644 --- a/readme.md +++ b/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, // 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``); + const element = await webhelpers.fixture( + webhelpers.html`` + ); 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`
Content
`); - 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 diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 3ea9df1..3e7dc1c 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -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.' }