Klassijs 'soft assert' Assertion Tool

Overview

The Assertion Tool is designed to enhance your testing framework by allowing tests to continue running even when assertions fail. Instead of halting the test upon an assertion failure, this tool collects all failed assertions and compiles them into a comprehensive report at the end of the test run. This approach ensures that non-functional features do not prevent your tests from executing completely.

Features

• Non-blocking Assertions: Failures in assertions do not stop the execution of tests.
• Comprehensive Reporting: All failed assertions are accumulated and reported at the end of the test run.
• Easy Integration: Seamlessly integrates with your existing test framework.
• Full API Access: Provides access to the complete Chai API and expect-webdriverio functionality.
• Flexible Assertion Methods: Use predefined assertion types, any Chai/expect-webdriverio method, or custom functions.

Installation

To add the Assertion Tool to your project, follow these steps:

1. Add to project:

   1pnpm add klassijs-soft-assert

2. Import the tool into your test files:

   1const { softAssert, getExpect, getChai, getAssert, softAssertChai, softAssertExpect } = require('klassijs-soft-assert');

Usage

Method 1: Enhanced softAssert with Full API Access

The softAssert function now accepts any Chai or expect-webdriverio method directly:

1const { softAssert } = require('klassijs-soft-assert');
2
3// Any Chai assert method
4await softAssert(actual, 'deepEqual', expected, 'Deep equality check');
5await softAssert(actual, 'isArray', undefined, 'Should be an array');
6await softAssert(actual, 'include', expected, 'Should include value');
7
8// Any expect-webdriverio method
9await softAssert(element, 'toBeDisplayed', undefined, 'Element should be displayed');
10await softAssert(element, 'toHaveAttribute', 'class', 'Element should have class');
11await softAssert(element, 'toHaveText', expected, 'Element should have text');
12
13// Chained expect-webdriverio methods
14await softAssert(element, 'not.toBeEnabled', undefined, 'Element should not be enabled');
15await softAssert(element, 'not.toBeSelected', undefined, 'Element should not be selected');
16
17// Custom function
18await softAssert(actual, async (actual, expected) => {
19  // Your custom assertion logic
20  assert.deepEqual(actual, expected);
21}, expected, 'Custom assertion');

Method 2: Using Predefined Assertion Types (Backward Compatible)

Your existing code continues to work unchanged:

1const { softAssert } = require('klassijs-soft-assert');
2
3// Predefined assertion types
4await softAssert(actual, 'equals', expected, 'message');
5await softAssert(actual, 'tohavetext', expected, 'message');

Method 3: Direct Library Access

Get access to the complete libraries:

1const { getChai, getAssert } = require('klassijs-soft-assert');
2
3// Get the full Chai instance
4const chai = await getChai();
5const assert = await getAssert();
6
7// Use any method from these libraries
8assert.deepEqual(actual, expected);
9chai.expect(myValue).to.be.a('string');

Method 4: Soft Assertion Wrappers

Wrap any assertion in soft assert functionality:

1const { softAssertChai, softAssertExpect } = require('klassijs-soft-assert');
2
3// Wrap any Chai assertion
4await softAssertChai(async () => {
5  assert.deepEqual(actual, expected);
6}, 'Custom error message');
7
8// Wrap any expect-webdriverio assertion
9await softAssertExpect(async () => {
10  await expect(element).toHaveAttribute('class', 'active');
11}, 'Custom error message');

Example

Here's a comprehensive example showing the enhanced functionality:

1const {
2   softAssert,
3   getExpect,
4   getChai,
5   getAssert,
6   softAssertChai,
7   softAssertExpect,
8   throwCollectedErrors
9} = require('klassijs-soft-assert');
10
11describe('Sample Test Suite', async() => {
12   it('should run all tests and report failed assertions', async () => {
13      // Method 1: Enhanced softAssert with full API access
14      await softAssert(title, 'toHaveText', 'our priority', 'This will pass');
15      await softAssert(elem.elementId, 'deepEqual', null, 'This will pass');
16      await softAssert(element, 'toBeDisplayed', undefined, 'Element should be displayed');
17      await softAssert(element, 'not.toBeEnabled', undefined, 'Element should not be enabled');
18
19      // Method 2: Backward compatible
20      await softAssert(title, 'tohavetext', 'our priority', 'This will pass');
21      await softAssert(elem.elementId,'equal', null, 'This will pass');
22
23      // Method 3: Custom function
24      await softAssert(actual, async (actual, expected) => {
25         const assert = await getAssert();
26         assert.deepEqual(actual, expected);
27      }, expected, 'Custom deep equality check');
28
29      // Method 4: Direct library usage (fails immediately)
30      const assert = await getAssert();
31      assert.isArray(myArray);
32   });
33
34   afterEach(async () => {
35      // Throw all collected errors at the end
36      throwCollectedErrors();
37   });
38});

Available Functions

• softAssert(actual, assertionType, expected, message, operator) - Enhanced function that accepts any Chai/expect-webdriverio method
• getExpect() - Get the full expect-webdriverio instance
• getChai() - Get the full Chai instance
• getAssert() - Get the Chai assert instance
• softAssertChai(assertionFunction, message) - Wrap any Chai assertion in soft assert
• softAssertExpect(assertionFunction, message) - Wrap any expect-webdriverio assertion in soft assert
• throwCollectedErrors() - Throw all collected errors at the end of the test

Supported Methods

Chai Assert Methods

Any method from chai.assert can be used directly:

• deepEqual, equal, notEqual, strictEqual, notStrictEqual
• isTrue, isFalse, isNull, isNotNull, isUndefined
• isArray, isString, isNumber, isBoolean, isFunction
• include, notInclude, match, lengthOf
• isEmpty, isNotEmpty, exists, notExists
• And many more...

Expect-WebdriverIO Methods

Any method from expect-webdriverio can be used directly:

• toBeDisplayed, toBeEnabled, toBeSelected, toBeChecked
• toHaveText, toHaveAttribute, toHaveHTML, toHaveTitle
• toHaveUrl, toBeClickable, toBeFocused, toBePresent
• toEqual, toContain, toBeExisting
• Chained methods like not.toBeEnabled, not.toBeSelected
• And many more...

Contributing

Contributions are welcome! If you have suggestions for improvements or bug fixes, feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.