5.5.3

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2024-11-23 - 5.5.3 - fix(docs)
+Update description and keywords in package files for clarity
+
+- Updated project description in package.json and npmextra.json for better clarity.
+- Enhanced keywords list in package.json and npmextra.json to cover more relevant topics.
+- Revised README.md content to provide a more comprehensive usage guide and correct mismatched sections.
+
 ## 2024-11-23 - 5.5.2 - fix(core)
 Apply code cleanup and refactoring.
 

npmextra.json

@@ -14,22 +14,32 @@
       "githost": "code.foss.global",
       "gitscope": "push.rocks",
       "gitrepo": "tapbundle",
-      "description": "A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for 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.",
       "npmPackagename": "@push.rocks/tapbundle",
       "license": "MIT",
       "keywords": [
         "testing",
         "automation",
         "TAP",
-        "test anything protocol",
+        "Test Anything Protocol",
         "unit testing",
         "integration testing",
-        "JavaScript",
         "TypeScript",
+        "JavaScript",
         "test runner",
         "test framework",
         "web helpers",
-        "test utilities"
+        "test utilities",
+        "asynchronous testing",
+        "environment variables",
+        "crypto",
+        "shell commands",
+        "Node.js",
+        "cloud storage",
+        "browser testing",
+        "UI components",
+        "parallel testing",
+        "test lifecycle management"
       ]
     }
   },

package.json

@@ -1,8 +1,8 @@
 {
   "name": "@push.rocks/tapbundle",
   "private": false,
-  "version": "5.5.2",
-  "description": "A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.",
+  "version": "5.5.3",
+  "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.",
   "exports": {
     ".": "./dist_ts/index.js",
     "./node": "./dist_ts_node/index.js"
@@ -68,14 +68,24 @@
     "testing",
     "automation",
     "TAP",
-    "test anything protocol",
+    "Test Anything Protocol",
     "unit testing",
     "integration testing",
-    "JavaScript",
     "TypeScript",
+    "JavaScript",
     "test runner",
     "test framework",
     "web helpers",
-    "test utilities"
+    "test utilities",
+    "asynchronous testing",
+    "environment variables",
+    "crypto",
+    "shell commands",
+    "Node.js",
+    "cloud storage",
+    "browser testing",
+    "UI components",
+    "parallel testing",
+    "test lifecycle management"
   ]
 }

readme.md

@@ -1,134 +1,209 @@
 # @push.rocks/tapbundle
 
-tap bundled for tapbuffer
+A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.
 
 ## Install
 
-Install the package by running the following command in your terminal:
+To install the package, execute:
 
 ```bash
 npm install @push.rocks/tapbundle --save-dev
 ```
 
-This will add `@push.rocks/tapbundle` to your project's `devDependencies`.
+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` package is a tap-compatible testing framework written in TypeScript, intended for use with tapbuffer. It includes a range of useful features enabling easy setup and execution of tests, assertion handling through `expect` and `expectAsync`, as well as auxiliary tools for delay and colored console output.
+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
+**Getting Started**
 
-First, ensure your project is set up with Typescript and supports ESM syntax. You can then import `tap`, `expect`, and `expectAsync` from `@push.rocks/tapbundle` to start defining your tests.
+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:
 
-```typescript
-import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
-```
+1. **Basic Setup**
 
-Here is a simple test example:
+   First, import the necessary modules:
 
-```typescript
-import { tap, expect } from '@push.rocks/tapbundle';
+   ```typescript
+   import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
+   ```
 
-tap.test('should succeed on true assertion', async () => {
-  return expect(true).toBeTrue();
-});
+   Start with a simple test to ensure everything is set up correctly:
 
-tap.start();
-```
+   ```typescript
+   import { tap, expect } from '@push.rocks/tapbundle';
 
-### Defining Tests
+   tap.test('Initial test succeeds', async () => {
+     return expect(true).toBeTrue();
+   });
 
-You can define tests with descriptions and async functions. The `tap` instance manages test execution, supports test skipping, and managing exclusive tests with the `.only` modifier.
+   tap.start();
+   ```
 
-```typescript
-const myTest = tap.test('expect true to be true', async () => {
-  expect(true).toBeTrue();
-});
+   The above code establishes a basic test environment, using the `tap` instance to manage execution flow and `expect` for assertions.
 
-const skippedTest = tap.skip.test('this test is skipped', async () => {
-  // This will not be executed
-});
+2. **Defining and Organizing Tests**
 
-tap.only.test('only this test will run', async () => {
-  expect('TapBundle').toContainString('Tap');
-});
+   You can define tests using the `tap.test` method, where you provide a description and an asynchronous function:
 
-tap.start();
-```
+   ```typescript
+   tap.test('basic arithmetic test', async () => {
+     expect(1 + 1).toEqual(2);
+   });
+   ```
 
-### Using `expect` and `expectAsync`
+   **Async Tests Handling**
 
-The package provides `expect` and `expectAsync` for assertions:
+   Use `expectAsync` for promises or async operations:
 
-```typescript
-await expectAsync(Promise.resolve(true)).toBeResolved();
-expect(5).toBeGreaterThan(2);
-```
+   ```typescript
+   tap.test('async operation test', async () => {
+     const fetchData = async () => Promise.resolve('data');
+     await expectAsync(fetchData()).toBeResolved();
+   });
+   ```
 
-### Handling Asynchronous Operations
+3. **Tools for Advanced Testing**
 
-`tapbundle` facilitates working with async operations in tests. You can introduce delays or set timeouts:
+   `tapbundle` equips you with tools for sophisticated test scenarios:
 
-```typescript
-tap.test('async operation with delay', async (tools) => {
-  await tools.delayFor(2000); // Wait for 2000 milliseconds
-  expect(true).toBeTrue();
-});
+   - **Delay and Timing**
 
-tap.start();
-```
+     Integrated delay methods are handy for simulating timeouts and waiting states:
 
-### Advanced Usage
+     ```typescript
+     tap.test('test with delay', async (tools) => {
+       await tools.delayFor(500); // waits for 500ms
+       expect(true).toBeTrue();
+     });
+     ```
 
-#### Pre Tasks
+   - **Custom Pre Tasks**
 
-You can define tasks to run before test execution begins:
+     Set up tasks to run before your test suite begins. This can be setup operations like initializing databases:
 
-```typescript
-tap.preTask('setup database', async () => {
-  // Perform setup here
-});
+     ```typescript
+     tap.preTask('initialize environment', async () => {
+       console.log('Setting up preconditions');
+     });
+     ```
 
-tap.test('test database connection', async () => {
-  // Test the setup
-});
+4. **Execution and Control**
 
-tap.start();
-```
+   - **Running Tests**
 
-#### Accessing Test Metadata
+     Call `tap.start()` to execute your suite. Handle specific conditions using `.skip` or `.only`:
 
-Each test returns a `TapTest` instance, from which you can access metadata and manipulate test behavior:
+     ```typescript
+     tap.skip.test('skip this test', async () => {
+       // This test will be ignored
+     });
 
-```typescript
-const test = tap.test('metadata example', async (tools) => {
-  tools.allowFailure();
-  expect(true).toBeTrue();
-});
+     tap.only.test('run this test exclusively', async () => {
+       // Only this test will run among defined tests
+     });
+     ```
 
-tap.start().then(() => {
-  console.log(`Test duration: ${test.hrtMeasurement.milliSeconds}ms`);
-});
-```
+   - **Handling Errors and Debugging**
 
-### Running Tests
+     Make use of `consolecolor` to make outputs readable:
 
-Tests are executed by calling `tap.start()`. This method runs all defined tests in sequence and respects `.skip` and `.only` modifiers.
+     ```typescript
+     tap.test('test with colored output', async (tools) => {
+       const message = await tools.coloredString('Test Passed!', 'green');
+       console.log(message);
+     });
+     ```
 
-### Debugging and Output
+5. **Integration with Node Tools**
 
-`@push.rocks/tapbundle` supports colored console output via `consolecolor` to help with debugging and test result readability:
+   For operations involving the shell or environment-specific setups, use Node tools provided:
 
-```typescript
-tap.test('colored output', async (tools) => {
-  const coloredString = await tools.coloredString('Hello, world!', 'green');
-  console.log(coloredString);
-});
+   ```typescript
+   import { tapNodeTools } from './ts_node/index.js';
 
-tap.start();
-```
+   tap.test('execute shell command', async () => {
+     const result = await tapNodeTools.runCommand('ls -la');
+     expect(result.exitCode).toEqual(0);
+   });
 
-This detailed guide covers the most important aspects of using `@push.rocks/tapbundle` for testing in your TypeScript projects. Explore the included functions and tools to fully leverage this comprehensive testing framework.
+   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`:
+
+   ```typescript
+   tap.test('use environment variable', async (tools) => {
+     const dbUrl = await tools.getEnvVarOnDemand('DB_URL');
+     expect(dbUrl).toBeDefined();
+   });
+   ```
+
+7. **Managing Asynchronous Behavior**
+
+   The framework allows for precise control over asynchronous processes, introducing race conditions or coordinated delays:
+
+   ```typescript
+   tap.test('controlled async scenario', async (tools) => {
+     const asyncOp = async () => Promise.resolve('complete');
+     tools.timeout(1000); // if operation exceeds 1000ms, test fails
+     const result = await asyncOp();
+     expect(result).toBe('complete');
+   });
+   ```
+
+8. **Web Testing Utilities**
+
+   If your testing involves browser environments, make use of the `webhelpers` utilities, for instance with libraries like Open WC:
+
+   ```typescript
+   import { webhelpers } from './webhelpers.js';
+
+   tap.test('web component test', async () => {
+     const element = await webhelpers.fixture(webhelpers.html`<my-element></my-element>`);
+     expect(element.shadowRoot.querySelector('div')).toBeDefined();
+   });
+   ```
+
+9. **Using Webhelpers in Browser**
+
+   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');
+   });
+
+   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');
+   });
+   ```
+
+10. **Leveraging Smartmongo and Smarts3**
+
+    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!
 
 ## License and Legal Information
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/tapbundle',
-  version: '5.5.2',
-  description: 'A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.'
+  version: '5.5.3',
+  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.'
 }