fix(docs): Update description and keywords in package files for clarity
This commit is contained in:
parent
8dd8ce1b15
commit
c84a7192fb
@ -1,5 +1,12 @@
|
||||
# Changelog
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
@ -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"
|
||||
]
|
||||
}
|
||||
},
|
||||
|
||||
18
package.json
18
package.json
@ -2,7 +2,7 @@
|
||||
"name": "@push.rocks/tapbundle",
|
||||
"private": false,
|
||||
"version": "5.5.2",
|
||||
"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.",
|
||||
"exports": {
|
||||
".": "./dist_ts/index.js",
|
||||
"./node": "./dist_ts_node/index.js"
|
||||
@ -68,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"
|
||||
]
|
||||
}
|
||||
233
readme.md
233
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
|
||||
|
||||
|
||||
@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@push.rocks/tapbundle',
|
||||
version: '5.5.2',
|
||||
description: 'A test automation library bundling utilities and tools for TAP (Test Anything Protocol) based testing, specifically tailored for tapbuffer.'
|
||||
version: '5.5.3',
|
||||
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.'
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user