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

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:

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

   Start with a simple test to ensure everything is set up correctly:

   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:

   tap.test('basic arithmetic test', async () => {
     expect(1 + 1).toEqual(2);
   });

   Async Tests Handling

   Use expectAsync for promises or async operations:

   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:

     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:

     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:

     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:

     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:

   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:

   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:

   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:

   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:

   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:

    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 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 [email protected].

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.