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

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.

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

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

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

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-----');
});

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

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');
});

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

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');
});

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.