5.5.5

changelog.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 2025-01-19 - 5.5.5 - fix(dependencies)
+Update dependencies to the latest versions to address multiple fixes.
+
+- Updated @push.rocks/smartexpect to version ^1.4.0.
+- Updated @push.rocks/smartfile to version ^11.1.5.
+- Updated @push.rocks/smartpromise to version ^4.1.0.
+- Updated @types/node to version ^22.10.7.
+- Updated randomstring to version ^1.3.1.
+
+## 2024-12-30 - 5.5.4 - fix(dependencies)
+Update package dependencies to their latest versions.
+
+- Updated @push.rocks/smartexpect from ^1.2.1 to ^1.3.0.
+- Updated @push.rocks/smartfile from ^11.0.21 to ^11.0.23.
+- Updated @push.rocks/smartshell from ^3.0.6 to ^3.2.2.
+- Updated @push.rocks/smarttime from ^4.0.8 to ^4.1.1.
+- Updated @types/node from ^22.9.3 to ^22.10.2.
+
+## 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.
+
+
+## 2024-11-23 - 5.5.1 - fix(core)
+Update dependencies and add jestExpect export
+
+- Updated '@push.rocks/qenv' to '^6.1.0' in dependencies.
+- Updated 'expect' package version to '^29.7.0' in dependencies.
+- Updated '@types/node' to '^22.9.3' in devDependencies.
+- Added jestExpect export in ts_node/index.ts.
+
+## 2024-11-06 - 5.5.0 - feat(tapnodetools)
+Add TestFileProvider for handling Docker Alpine image
+
+- Introduced TestFileProvider in TapNodeTools.
+- Added method to retrieve Docker Alpine image as a local tarball.
+
+## 2024-11-06 - 5.4.4 - fix(dependencies)
+Update smarts3 dependency to version 2.2.5
+
+
+## 2024-11-06 - 5.4.3 - fix(TapNodeTools)
+Fix server port default value in createSmarts3 method
+
+- The `createSmarts3` method in `TapNodeTools` now explicitly sets the port to 3003.
+
 ## 2024-11-06 - 5.4.2 - fix(dependencies)
 Update smarts3 dependency version to fix issues.
 

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.4.2",
-  "description": "A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.",
+  "version": "5.5.5",
+  "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"
@@ -26,24 +26,28 @@
   "dependencies": {
     "@open-wc/testing": "^4.0.0",
     "@push.rocks/consolecolor": "^2.0.2",
-    "@push.rocks/qenv": "^6.0.5",
+    "@push.rocks/qenv": "^6.1.0",
     "@push.rocks/smartcrypto": "^2.0.4",
     "@push.rocks/smartdelay": "^3.0.5",
     "@push.rocks/smartenv": "^5.0.12",
-    "@push.rocks/smartexpect": "^1.2.1",
+    "@push.rocks/smartexpect": "^1.4.0",
+    "@push.rocks/smartfile": "^11.1.5",
     "@push.rocks/smartjson": "^5.0.20",
     "@push.rocks/smartmongo": "^2.0.10",
-    "@push.rocks/smartpromise": "^4.0.4",
-    "@push.rocks/smarts3": "^2.2.2",
-    "@push.rocks/smartshell": "^3.0.6",
-    "@push.rocks/smarttime": "^4.0.8"
+    "@push.rocks/smartpath": "^5.0.18",
+    "@push.rocks/smartpromise": "^4.1.0",
+    "@push.rocks/smartrequest": "^2.0.23",
+    "@push.rocks/smarts3": "^2.2.5",
+    "@push.rocks/smartshell": "^3.2.2",
+    "@push.rocks/smarttime": "^4.1.1",
+    "expect": "^29.7.0"
   },
   "devDependencies": {
     "@git.zone/tsbuild": "^2.1.66",
     "@git.zone/tsrun": "^1.2.43",
     "@git.zone/tstest": "^1.0.77",
-    "@types/node": "^22.5.5",
-    "randomstring": "^1.3.0"
+    "@types/node": "^22.10.7",
+    "randomstring": "^1.3.1"
   },
   "files": [
     "ts/**/*",
@@ -64,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,138 +1,213 @@
 # @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
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

ts/00_commitinfo_data.ts

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

ts/tapbundle.classes.taptools.ts

@@ -60,5 +60,9 @@ export class TapTools {
     return plugins.smartpromise.defer();
   }
 
+  public cumulativeDefer() {
+    return plugins.smartpromise.cumulativeDefer();
+  }
+
   public smartjson = plugins.smartjson;
 }

ts_node/classes.tapnodetools.ts

@@ -1,7 +1,9 @@
+import { TestFileProvider } from './classes.testfileprovider.js';
 import * as plugins from './plugins.js';
 
 class TapNodeTools {
   private smartshellInstance: plugins.smartshell.Smartshell;
+  public testFileProvider = new TestFileProvider();
 
   constructor() {}
 
@@ -85,6 +87,7 @@ class TapNodeTools {
   public async createSmarts3() {
     const smarts3Mod = await import('@push.rocks/smarts3');
     const smarts3Instance = new smarts3Mod.Smarts3({
+      port: 3003,
       cleanSlate: true,
     });
     await smarts3Instance.start();

ts_node/classes.testfileprovider.ts

@@ -0,0 +1,17 @@
+import * as plugins from './plugins.js';
+import * as paths from './paths.js';
+
+export const fileUrls = {
+  dockerAlpineImage: 'https://code.foss.global/testassets/docker/raw/branch/main/alpine.tar',
+}
+
+export class TestFileProvider {
+  public async getDockerAlpineImageAsLocalTarball(): Promise<string> {
+    const filePath = plugins.path.join(paths.testFilesDir, 'alpine.tar')
+    // fetch the docker alpine image
+    const response = await plugins.smartrequest.getBinary(fileUrls.dockerAlpineImage);
+    await plugins.smartfile.fs.ensureDir(paths.testFilesDir);
+    await plugins.smartfile.memory.toFs(response.body, filePath);
+    return filePath;
+  }
+}

ts_node/index.ts

@@ -1 +1,5 @@
 export * from './classes.tapnodetools.js';
+
+import { expect as jestExpect } from 'expect';
+
+export { jestExpect };

ts_node/paths.ts

@@ -0,0 +1,4 @@
+import * as plugins from './plugins.js';
+
+export const cwd = process.cwd();
+export const testFilesDir = plugins.path.join(cwd, './.nogit/testfiles/');

ts_node/plugins.ts

@@ -1,12 +1,16 @@
 // node native
 import * as crypto from 'crypto';
 import * as fs from 'fs';
+import * as path from 'path';
 
-export { crypto,fs };
+export { crypto,fs, path, };
 
 // @push.rocks scope
 import * as qenv from '@push.rocks/qenv';
 import * as smartcrypto from '@push.rocks/smartcrypto';
+import * as smartfile from '@push.rocks/smartfile';
+import * as smartpath from '@push.rocks/smartpath';
+import * as smartrequest from '@push.rocks/smartrequest';
 import * as smartshell from '@push.rocks/smartshell';
 
-export { qenv, smartcrypto, smartshell };
+export { qenv, smartcrypto, smartfile, smartpath, smartrequest, smartshell, };