5.5.6

changelog.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 2025-01-19 - 5.5.6 - fix(dependencies)
+Update smartpromise dependency to version 4.2.0.
+
+- Updated @push.rocks/smartpromise dependency from version 4.1.0 to 4.2.0 in package.json.
+
+## 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.
+
+- Changed the version of @push.rocks/smarts3 from ^2.2.1 to ^2.2.2.
+
 ## 2024-11-06 - 5.4.1 - fix(ci)
 Fix CI configuration URL and package installation paths.
 

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.1",
-  "description": "A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.",
+  "version": "5.5.6",
+  "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.1",
-    "@push.rocks/smartshell": "^3.0.6",
-    "@push.rocks/smarttime": "^4.0.8"
+    "@push.rocks/smartpath": "^5.0.18",
+    "@push.rocks/smartpromise": "^4.2.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,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 () => {
+   Start with a simple test to ensure everything is set up correctly:
+
+   ```typescript
+   import { tap, expect } from '@push.rocks/tapbundle';
+
+   tap.test('Initial test succeeds', async () => {
      return expect(true).toBeTrue();
-});
+   });
 
-tap.start();
-```
+   tap.start();
+   ```
 
-### Defining Tests
+   The above code establishes a basic test environment, using the `tap` instance to manage execution flow and `expect` for assertions.
 
-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.
+2. **Defining and Organizing Tests**
 
-```typescript
-const myTest = tap.test('expect true to be true', async () => {
+   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
+   tap.test('async operation test', async () => {
+     const fetchData = async () => Promise.resolve('data');
+     await expectAsync(fetchData()).toBeResolved();
+   });
+   ```
+
+3. **Tools for Advanced Testing**
+
+   `tapbundle` equips you with tools for sophisticated test scenarios:
+
+   - **Delay and Timing**
+
+     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();
-});
+     });
+     ```
 
-const skippedTest = tap.skip.test('this test is skipped', async () => {
-  // This will not be executed
-});
+   - **Custom Pre Tasks**
 
-tap.only.test('only this test will run', async () => {
-  expect('TapBundle').toContainString('Tap');
-});
+     Set up tasks to run before your test suite begins. This can be setup operations like initializing databases:
 
-tap.start();
-```
+     ```typescript
+     tap.preTask('initialize environment', async () => {
+       console.log('Setting up preconditions');
+     });
+     ```
 
-### Using `expect` and `expectAsync`
+4. **Execution and Control**
 
-The package provides `expect` and `expectAsync` for assertions:
+   - **Running Tests**
 
-```typescript
-await expectAsync(Promise.resolve(true)).toBeResolved();
-expect(5).toBeGreaterThan(2);
-```
+     Call `tap.start()` to execute your suite. Handle specific conditions using `.skip` or `.only`:
 
-### Handling Asynchronous Operations
+     ```typescript
+     tap.skip.test('skip this test', async () => {
+       // This test will be ignored
+     });
 
-`tapbundle` facilitates working with async operations in tests. You can introduce delays or set timeouts:
+     tap.only.test('run this test exclusively', async () => {
+       // Only this test will run among defined tests
+     });
+     ```
 
-```typescript
-tap.test('async operation with delay', async (tools) => {
-  await tools.delayFor(2000); // Wait for 2000 milliseconds
-  expect(true).toBeTrue();
-});
+   - **Handling Errors and Debugging**
 
-tap.start();
-```
+     Make use of `consolecolor` to make outputs readable:
 
-### Advanced Usage
+     ```typescript
+     tap.test('test with colored output', async (tools) => {
+       const message = await tools.coloredString('Test Passed!', 'green');
+       console.log(message);
+     });
+     ```
 
-#### Pre Tasks
+5. **Integration with Node Tools**
 
-You can define tasks to run before test execution begins:
+   For operations involving the shell or environment-specific setups, use Node tools provided:
 
-```typescript
-tap.preTask('setup database', async () => {
-  // Perform setup here
-});
+   ```typescript
+   import { tapNodeTools } from './ts_node/index.js';
 
-tap.test('test database connection', async () => {
-  // Test the setup
-});
+   tap.test('execute shell command', async () => {
+     const result = await tapNodeTools.runCommand('ls -la');
+     expect(result.exitCode).toEqual(0);
+   });
 
-tap.start();
-```
+   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-----');
+   });
+   ```
 
-#### Accessing Test Metadata
+6. **Working with Environment Variables**
 
-Each test returns a `TapTest` instance, from which you can access metadata and manipulate test behavior:
+   Leverage the power of dynamic environment management using `qenv`:
 
-```typescript
-const test = tap.test('metadata example', async (tools) => {
-  tools.allowFailure();
-  expect(true).toBeTrue();
-});
+   ```typescript
+   tap.test('use environment variable', async (tools) => {
+     const dbUrl = await tools.getEnvVarOnDemand('DB_URL');
+     expect(dbUrl).toBeDefined();
+   });
+   ```
 
-tap.start().then(() => {
-  console.log(`Test duration: ${test.hrtMeasurement.milliSeconds}ms`);
-});
-```
+7. **Managing Asynchronous Behavior**
 
-### Running Tests
+   The framework allows for precise control over asynchronous processes, introducing race conditions or coordinated delays:
 
-Tests are executed by calling `tap.start()`. This method runs all defined tests in sequence and respects `.skip` and `.only` modifiers.
+   ```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');
+   });
+   ```
 
-### Debugging and Output
+8. **Web Testing Utilities**
 
-`@push.rocks/tapbundle` supports colored console output via `consolecolor` to help with debugging and test result readability:
+   If your testing involves browser environments, make use of the `webhelpers` utilities, for instance with libraries like Open WC:
 
-```typescript
-tap.test('colored output', async (tools) => {
-  const coloredString = await tools.coloredString('Hello, world!', 'green');
-  console.log(coloredString);
-});
+   ```typescript
+   import { webhelpers } from './webhelpers.js';
 
-tap.start();
-```
+   tap.test('web component test', async () => {
+     const element = await webhelpers.fixture(webhelpers.html`<my-element></my-element>`);
+     expect(element.shadowRoot.querySelector('div')).toBeDefined();
+   });
+   ```
 
-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.
+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.4.1',
-  description: 'A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.'
+  version: '5.5.6',
+  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, };