tapbundle/readme.md

# @push.rocks/tapbundle

A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.

## Install

To install the package, execute:

```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.

**Getting Started**

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:

1. **Basic Setup**

   First, import the necessary modules:

   ```typescript
   import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
   ```

   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();
   ```

   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
   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();
     });
     ```

   - **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:

   ```typescript
   import { tapNodeTools } from './ts_node/index.js';

   tap.test('execute shell command', async () => {
     const result = await tapNodeTools.runCommand('ls -la');
     expect(result.exitCode).toEqual(0);
   });

   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. 

**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.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.