@cuppet/core 1.2.5 → 1.3.1

package/README.md

@@ -132,8 +132,8 @@ For a detailed configuration and step definitions guide, see [GUIDE.MD](./GUIDE.
 
 This package requires the following peer dependencies:
 
-- `@cucumber/cucumber` ^11.0.0
-- `config` ^3.3.9
+- `@cucumber/cucumber` ^12.0.0
+- `config` ^4.1.0
 
 Make sure to install these in your project:
 

package/features/app/hooks.js

@@ -1,7 +1,5 @@
 const { BeforeAll, AfterAll, Before, After, AfterStep, Status } = require('@cucumber/cucumber');
-const BrowserManager = require('./browserManager');
-const AppiumManager = require('./appiumManager');
-const MqttManager = require('./mqttManager');
+const { BrowserManager, AppiumManager, MqttManager, KafkaManager } = require('./managers');
 const fs = require('fs');
 const config = require('config');
 const dataStore = require('../../src/dataStorage');
@@ -68,6 +66,7 @@ Before(async function (testCase) {
     const appiumTag = arrayTags.find((item) => item.name === '@appium');
     const mqttTag = arrayTags.find((item) => item.name === '@mqtt');
     const apiTag = arrayTags.find((item) => item.name === '@api');
+    const kafkaTag = arrayTags.find((item) => item.name === '@kafka');
 
     // Initialize MQTT Manager if @mqtt tag is present
     if (mqttTag) {
@@ -76,8 +75,15 @@ Before(async function (testCase) {
         this.mqttManager = mqttManager;
     }
 
+    // Initialize Kafka Manager if @kafka tag is present
+    if (kafkaTag) {
+        const kafkaManager = new KafkaManager();
+        await kafkaManager.initialize();
+        this.kafkaManager = kafkaManager;
+    }
+
     // Initialize browser unless it's API-only or MQTT-only test
-    if (!appiumTag && !apiTag && !mqttTag) {
+    if (!appiumTag && !apiTag && !mqttTag && !kafkaTag) {
         const browserManager = new BrowserManager(browserViewport, browserArgs, credentials);
         await browserManager.initialize();
 
@@ -112,4 +118,10 @@ After(async function (testCase) {
     } else if (this.appiumDriver) {
         await this.appiumManager.stop();
     }
+
+    // Cleanup Kafka connection if present
+    if (this.kafkaManager) {
+        await this.kafkaManager.stop();
+        this.kafkaManager = null;
+    }
 });

package/features/app/managers/index.js

@@ -0,0 +1,7 @@
+// features/app/managers/index.js
+module.exports = {
+    BrowserManager: require('./browserManager'),
+    AppiumManager: require('./appiumManager'),
+    MqttManager: require('./mqttManager'),
+    KafkaManager: require('./kafkaManager'),
+};

package/features/app/managers/kafkaManager.js

@@ -0,0 +1,180 @@
+const { Kafka, logLevel } = require('kafkajs');
+const config = require('config');
+
+/**
+ * KafkaManager class for managing Kafka client lifecycle
+ * Follows the same pattern as MqttManager and BrowserManager
+ */
+class KafkaManager {
+    constructor(customOptions = {}) {
+        this.kafka = null;
+        this.producer = null;
+        this.consumer = null;
+        this.options = this.prepareOptions(customOptions);
+        this.isInitialized = false;
+    }
+
+    /**
+     * Prepare Kafka connection options from config or provided options
+     * @param {Object} customOptions - Custom options to override config
+     * @returns {Object} - Kafka connection options
+     */
+    prepareOptions(customOptions) {
+        const defaultOptions = {
+            clientId: config.has('kafka.clientId')
+                ? config.get('kafka.clientId')
+                : `cuppet-test-${Math.random().toString(16).slice(2, 8)}`,
+            brokers: config.has('kafka.brokers') ? config.get('kafka.brokers') : ['localhost:9092'],
+            connectionTimeout: config.has('kafka.connectionTimeout') ? config.get('kafka.connectionTimeout') : 5000,
+            requestTimeout: config.has('kafka.requestTimeout') ? config.get('kafka.requestTimeout') : 30000,
+            logLevel: config.has('kafka.logLevel') ? Number(config.get('kafka.logLevel')) : logLevel.ERROR,
+        };
+
+        // Add SASL authentication if provided in config
+        if (config.has('kafka.sasl')) {
+            defaultOptions.sasl = config.get('kafka.sasl');
+        }
+
+        // Add SSL configuration if provided
+        if (config.has('kafka.ssl')) {
+            defaultOptions.ssl = config.get('kafka.ssl');
+        }
+
+        // Merge with custom options (custom options take precedence)
+        return { ...defaultOptions, ...customOptions };
+    }
+
+    /**
+     * Initialize Kafka client and test connection
+     * @returns {Promise<void>}
+     */
+    async initialize() {
+        try {
+            // Create Kafka instance
+            this.kafka = new Kafka(this.options);
+            console.log(`Successfully connected to Kafka`);
+            this.isInitialized = true;
+        } catch (error) {
+            throw new Error(`Failed to initialize Kafka client: ${error.message}`);
+        }
+    }
+
+    /**
+     * Create and connect a producer
+     * @param {Object} producerOptions - Producer configuration options
+     * @returns {Promise<Object>} - Connected producer instance
+     */
+    async createProducer(producerOptions = {}) {
+        if (!this.isInitialized) {
+            throw new Error('Kafka client not initialized. Call initialize() first.');
+        }
+        this.producer = this.kafka.producer(producerOptions);
+        await this.producer.connect();
+        return this.producer;
+    }
+
+    /**
+     * Create and connect a consumer
+     * @param {Object} consumerOptions - Consumer configuration options (must include groupId)
+     * @returns {Promise<Object>} - Connected consumer instance
+     */
+    async createConsumer(consumerOptions = {}) {
+        if (!this.isInitialized) {
+            throw new Error('Kafka client not initialized. Call initialize() first.');
+        }
+
+        if (!consumerOptions.groupId) {
+            consumerOptions.groupId = `cuppet-test-${Math.random().toString(16).slice(2, 8)}`;
+        }
+
+        this.consumer = this.kafka.consumer(consumerOptions);
+        await this.consumer.connect();
+        return this.consumer;
+    }
+
+    /**
+     * Check if Kafka client is initialized
+     * @returns {boolean}
+     */
+    isReady() {
+        return this.isInitialized;
+    }
+
+    /** Send a message to a topic (currently only supports one message at a time)
+     * @param {string} topic - Topic to send message to
+     * @param {Object} message - Message to send. An object with key and value properties.
+     * @returns {Promise<void>}
+     */
+    async sendMessage(topic, message = {}) {
+        if (!this.producer) {
+            await this.createProducer();
+        }
+        await this.producer.send({
+            topic,
+            messages: [message],
+        });
+    }
+
+    /** Subscribe to a topic
+     * @param {Array} topics - Array of topics to subscribe to
+     * @returns {Promise<Object>} - Object with topic, partition, and message properties
+     */
+    async subscribeToTopics(topics = []) {
+        if (!this.consumer) {
+            await this.createConsumer();
+        }
+        await this.consumer.subscribe({
+            topics: topics,
+        });
+    }
+
+    /** Consume a message from a topic
+     * @returns {Promise<Object>} - Object with topic, partition, and message properties
+     */
+    async consumeMessage() {
+        return new Promise((resolve) => {
+            this.consumer.run({
+                eachMessage: async ({ topic, partition, message }) => {
+                    resolve({ topic, partition, message });
+                },
+            });
+        });
+    }
+
+    /** Disconnect from all topics
+     * @returns {Promise<void>}
+     */
+    async disconnect() {
+        await this.consumer.stop();
+        await this.consumer.disconnect();
+    }
+
+    /**
+     * Stop all Kafka connections and cleanup
+     * @returns {Promise<void>}
+     */
+    async stop() {
+        const disconnectPromises = [];
+        try {
+            if (this.producer) {
+                disconnectPromises.push(this.producer.disconnect());
+            }
+
+            if (this.consumer) {
+                disconnectPromises.push(this.consumer.disconnect());
+            }
+
+            await Promise.all(disconnectPromises);
+            console.log('Kafka client stopped successfully');
+        } catch (error) {
+            throw new Error(`Error during Kafka client cleanup: ${error.message}`);
+        } finally {
+            this.producer = null;
+            this.consumer = null;
+            this.kafka = null;
+            this.isInitialized = false;
+        }
+    }
+}
+
+module.exports = KafkaManager;

package/features/app/stepDefinitions/kafkaSteps.js

@@ -0,0 +1,71 @@
+const { Given, When, Then } = require('@cucumber/cucumber');
+const kafkaFunctions = require('../../../src/kafkaFunctions');
+
+Given('I subscribe to Kafka topic/topics {string}', async function (topics) {
+    await kafkaFunctions.subscribeToTopics(this.kafkaManager, topics);
+});
+
+Given('I listen for a kafka message on the subscribed topics', async function () {
+    await kafkaFunctions.listenForMessage(this.kafkaManager);
+});
+
+Given('I unsubscribe from all Kafka topics', async function () {
+    await kafkaFunctions.unsubscribeFromAllTopics(this.kafkaManager);
+});
+
+Then('I should receive a kafka message with key {string} and value {string}', async function (key, value) {
+    await kafkaFunctions.validateSimpleMessage(value, key);
+});
+
+Then('I should receive a kafka message with value {string}', async function (value) {
+    await kafkaFunctions.validateSimpleMessage(value);
+});
+
+Then('I should receive a kafka message with property {string} and value {string}', async function (property, value) {
+    await kafkaFunctions.validateJsonMessageContains(property, value);
+});
+
+Then(
+    'I should receive a kafka message with property {string} and value {string} and key {string}',
+    async function (property, value, key) {
+        await kafkaFunctions.validateJsonMessageContains(property, value, true, key);
+    }
+);
+
+Then(
+    'I should receive a kafka message with property {string} and key {string} which value does not match {string}',
+    async function (property, key, value) {
+        await kafkaFunctions.validateJsonMessageContains(property, value, false, key);
+    }
+);
+
+Then(
+    'I should receive a kafka message with property {string} which value does not match {string}',
+    async function (property, value) {
+        await kafkaFunctions.validateJsonMessageContains(property, value, false);
+    }
+);
+
+When('I send a kafka message to topic {string} with value {string}', async function (topic, message) {
+    await kafkaFunctions.sendMessage(this.kafkaManager, topic, message);
+});
+
+When(
+    'I send a kafka message to topic {string} with value {string} and key {string}',
+    async function (topic, message, key) {
+        await kafkaFunctions.sendMessage(this.kafkaManager, topic, message, key);
+    }
+);
+
+When(
+    'I send a kafka message to topic {string} with key {string} and JSON value',
+    async function (topic, key, docString) {
+        const message = JSON.stringify(docString);
+        await kafkaFunctions.sendMessage(this.kafkaManager, topic, message, key);
+    }
+);
+
+When('I send a kafka message to topic {string} with JSON value', async function (topic, docString) {
+    const message = JSON.stringify(docString);
+    await kafkaFunctions.sendMessage(this.kafkaManager, topic, message);
+});

package/features/app/stepDefinitions/mqttSteps.js

@@ -27,6 +27,10 @@ When('I unsubscribe from MQTT topic {string}', async function (topic) {
     await mqttFunctions.unsubscribeFromTopic(this.mqttManager, topic);
 });
 
+When('I prepare MQTT message as JSON', async function (docString) {
+    await mqttFunctions.prepareMessage(docString, true);
+});
+
 /**
  * Publish a message to an MQTT topic
  * @example When I publish "Hello World" to MQTT topic "test/message"
@@ -168,7 +172,7 @@ Then('I should have received {int} messages on MQTT topic {string}', async funct
  * These are not needed if using the @mqtt tag (connection is automatic)
  */
 Given('I connect to MQTT broker {string}', async function (brokerUrl) {
-    const MqttManager = require('../mqttManager');
+    const { MqttManager } = require('../managers');
     const mqttManager = new MqttManager(brokerUrl);
     await mqttManager.initialize();
     this.mqttManager = mqttManager;

package/features/tests/example-kafka.feature

@@ -0,0 +1,16 @@
+@kafka
+Feature: Kafka Testing Examples
+  Test Kafka messaging functionality using Cucumber and kafka.js
+
+    Scenario: Simple message publish and receive
+    Given I subscribe to Kafka topic "testTopic"
+    Then I listen for a kafka message on the subscribed topics
+    Then I should receive a kafka message with property "message" and value "test"
+    And I unsubscribe from all Kafka topics
+    When I send a kafka message to topic "testTopic" with JSON value
+      """
+      {
+        "message": "test3"
+      }
+      """
+   

package/index.js

@@ -12,11 +12,10 @@ const appiumTesting = require('./src/appiumTesting');
 const accessibilityTesting = require('./src/accessibilityTesting');
 const lighthouse = require('./src/lighthouse');
 const visualRegression = require('./src/visualRegression');
+const kafkaFunctions = require('./src/kafkaFunctions');
 
 // Export managers
-const BrowserManager = require('./features/app/browserManager');
-const AppiumManager = require('./features/app/appiumManager');
-const MqttManager = require('./features/app/mqttManager');
+const { BrowserManager, AppiumManager, MqttManager, KafkaManager } = require('./features/app/managers');
 
 // Export step definitions
 const stepDefinitions = require('./stepDefinitions');
@@ -29,6 +28,7 @@ module.exports = {
     helperFunctions,
     apiFunctions,
     mqttFunctions,
+    kafkaFunctions,
     appiumTesting,
     accessibilityTesting,
     lighthouse,
@@ -38,6 +38,7 @@ module.exports = {
     BrowserManager,
     AppiumManager,
     MqttManager,
+    KafkaManager,
 
     // Step definitions
     stepDefinitions,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cuppet/core",
-    "version": "1.2.5",
+    "version": "1.3.1",
     "description": "Core testing framework components for Cuppet - BDD framework based on Cucumber and Puppeteer",
     "main": "index.js",
     "files": [
@@ -36,6 +36,7 @@
         "axios": "^1.11.0",
         "backstopjs": "^6.3.25",
         "chai": "6.0.1",
+        "kafkajs": "^2.2.4",
         "lighthouse": "^12.8.0",
         "mime": "^3.0.0",
         "mime-types": "^3.0.1",
@@ -65,10 +66,11 @@
     },
     "scripts": {
         "test": "cucumber-js features/tests/example.feature",
+        "run:kafka": "cucumber-js features/tests/example-kafka.feature",
         "run:visual": "cucumber-js features/tests/example-visual-test.feature",
         "run:pa11y": "cucumber-js features/tests/example-pa11y.feature",
         "run:lighthouse": "cucumber-js features/tests/example-lighthouse.feature",
-        "run:mqtt": "cucumber-js features/tests/mqttExample.feature",
+        "run:mqtt": "cucumber-js features/tests/example-mqtt.feature",
         "run:mobile": "cucumber-js features/tests/example-mobile.feature",
         "run:accessibility": "cucumber-js features/tests/example-accessibility.feature",
         "run:performance": "cucumber-js features/tests/example-performance.feature",

package/src/kafkaFunctions.js

@@ -0,0 +1,170 @@
+const storage = require('./dataStorage');
+const assert = require('chai').assert;
+const helperFunctions = require('./helperFunctions');
+
+module.exports = {
+    /** @type {Object} */
+    messageObject: null,
+
+    /**
+     * Subscribe to a topic
+     * @param {object} kafkaManager - Kafka manager instance
+     * @param {string} topics - String, comma separated list of topics to subscribe to
+     * @returns {Promise<void>}
+     */
+    subscribeToTopics: async function (kafkaManager, topics) {
+        const resolvedTopics = await this.prepareTopics(topics);
+        const topicsArray = resolvedTopics.split(',');
+        await kafkaManager.subscribeToTopics(topicsArray);
+    },
+
+    /**
+     * Listen for a message on the subscribed topics
+     * @param {object} kafkaManager - Kafka manager instance
+     * @returns {Promise<void>}
+     */
+    listenForMessage: async function (kafkaManager) {
+        this.messageObject = await kafkaManager.consumeMessage();
+        return this.messageObject;
+    },
+
+    /**
+     * Disconnect from all topics
+     * @param {object} kafkaManager - Kafka manager instance
+     * @returns {Promise<void>}
+     */
+    unsubscribeFromAllTopics: async function (kafkaManager) {
+        await kafkaManager.disconnect();
+        delete this.messageObject;
+    },
+
+    /**
+     * Prepare topic by replacing variables
+     * @param {string} topic - Topic with potential variables
+     * @returns {Promise<string>} - Resolved topic
+     */
+    prepareTopics: async function (topics) {
+        return await storage.checkForMultipleVariables(topics);
+    },
+
+    /**
+     * Prepare message by replacing variables
+     * @param {string} message - Message with potential variables
+     * @returns {Promise<Object>} - Resolved message as JSON object
+     */
+    prepareMessage: async function (message) {
+        const resolvedMessage = await storage.checkForMultipleVariables(message);
+        try {
+            const jsonObject = JSON.parse(resolvedMessage);
+            return jsonObject;
+        } catch {
+            // If the message is not a valid JSON object, return it as a string
+            return resolvedMessage;
+        }
+    },
+
+    /**
+     * Validate that the message key equals the expected value
+     * @param {string} key - Key to validate
+     * @returns {Promise<void>}
+     */
+    validateMessageKeyEquals: async function (key) {
+        const resolvedKey = await storage.checkForSavedVariable(key);
+        const messageKey = this.messageObject?.key?.toString();
+        if (!messageKey) {
+            throw new Error(`Message key is not present in the message object`);
+        }
+        assert.strictEqual(
+            messageKey,
+            resolvedKey,
+            `Message key does not match. Expected: ${resolvedKey}, Actual: ${messageKey}`
+        );
+    },
+
+    /**
+     * Validate that the message object has a value property containing the actual message
+     * @returns {Promise<string>} - Message value
+     */
+    validateMessageHasValue: function () {
+        const messageValue = this.messageObject?.message?.value?.toString();
+        if (!messageValue) {
+            throw new Error(`Message value is not present in the message object`);
+        }
+        return messageValue;
+    },
+
+    /**
+     * Read the message from the message object
+     * @param {string} key - Key to validate
+     * @param {string} value - Value to validate
+     * @returns {Promise<void>}
+     */
+    validateSimpleMessage: async function (value, key = null) {
+        if (key) {
+            await this.validateMessageKeyEquals(key);
+        }
+        const resolvedValue = await storage.checkForMultipleVariables(value);
+        const messageValue = this.validateMessageHasValue();
+        assert.strictEqual(
+            messageValue,
+            resolvedValue,
+            `Message does not match. Expected: ${resolvedValue}, Actual: ${messageValue}`
+        );
+    },
+
+    /**
+     * Validate that a JSON message contains a property with a specific value
+     * @param {string} property - Property path to validate (e.g., "eventType" or "payload.metadata.userId")
+     * @param {string} value - Expected value (or null to just check property exists)
+     * @param {boolean} contains - Whether the property should match (true) or NOT match (false) the value
+     * @param {string} key - Key to validate (optional)
+     * @returns {Promise<void>}
+     */
+    validateJsonMessageContains: async function (property, value, contains = true, key = null) {
+        if (key) {
+            await this.validateMessageKeyEquals(key);
+        }
+
+        const messageValue = this.validateMessageHasValue();
+        // Parse the message value to a JSON object
+        let jsonData;
+        try {
+            jsonData = JSON.parse(messageValue);
+        } catch (error) {
+            throw new Error(`The message value is not a valid JSON object: ${error.message}`);
+        }
+        // Get the property value using helperFunctions (handles nested properties)
+        const actualValue = helperFunctions.getPropertyValue(jsonData, property);
+        const resolvedValue = await storage.checkForMultipleVariables(value);
+
+        if (contains) {
+            assert.strictEqual(
+                actualValue?.toString(),
+                resolvedValue,
+                `Value of property "${property}" does not match. Expected: ${resolvedValue}, Actual: ${actualValue}`
+            );
+        } else {
+            assert.notStrictEqual(
+                actualValue?.toString(),
+                resolvedValue,
+                `Value of property "${property}" should NOT match but it does. Value: ${resolvedValue}`
+            );
+        }
+    },
+
+    /**
+     * Send a message to a topic
+     * @param {object} kafkaManager - Kafka manager instance
+     * @param {string} topic - Topic to send message to
+     * @param {object|string} message - Message to send. Can be a JSON object or a string.
+     * @returns {Promise<void>}
+     */
+    sendMessage: async function (kafkaManager, topic, message, key = null) {
+        const resolvedMessage = await this.prepareMessage(message);
+        const messageObject = {
+            ...(key && { key: await storage.checkForSavedVariable(key) }),
+            value: typeof resolvedMessage === 'object' ? JSON.stringify(resolvedMessage) : resolvedMessage,
+        };
+        await kafkaManager.sendMessage(topic, messageObject);
+    },
+};

package/src/mqttFunctions.js

@@ -7,6 +7,9 @@ const helper = require('./helperFunctions');
  * Provides core MQTT testing operations following the same pattern as Puppeteer and Appium functions
  */
 module.exports = {
+    /** @type {Object} */
+    messageObject: null,
+
     /**
      * Prepare topic by replacing variables
      * @param {string} topic - Topic with potential variables
@@ -21,8 +24,17 @@ module.exports = {
      * @param {string} message - Message with potential variables
      * @returns {Promise<string>} - Resolved message
      */
-    prepareMessage: async function (message) {
-        return await storage.checkForMultipleVariables(message);
+    prepareMessage: async function (message, json = false) {
+        const resolvedMessage = await storage.checkForMultipleVariables(message);
+        if (json) {
+            try {
+                this.messageObject = JSON.parse(resolvedMessage);
+                return this.messageObject;
+            } catch (error) {
+                throw new Error(`Invalid JSON message: ${error.message}`);
+            }
+        }
+        return resolvedMessage;
     },
 
     /**
@@ -59,8 +71,9 @@ module.exports = {
      */
     publishMessage: async function (mqttManager, message, topic, qos = 0, retain = false) {
         const resolvedTopic = await this.prepareTopic(topic);
-        const resolvedMessage = await this.prepareMessage(message);
+        const resolvedMessage = this.messageObject || (await this.prepareMessage(message));
         await mqttManager.publish(resolvedTopic, resolvedMessage, { qos, retain });
+        delete this.messageObject;
     },
 
     /**
@@ -74,7 +87,7 @@ module.exports = {
      */
     publishJsonMessage: async function (mqttManager, jsonString, topic, qos = 0, retain = false) {
         const resolvedTopic = await this.prepareTopic(topic);
-        const resolvedJson = await this.prepareMessage(jsonString);
+        const resolvedJson = this.messageObject || (await this.prepareMessage(jsonString));
 
         // Validate JSON
         try {
@@ -84,6 +97,7 @@ module.exports = {
         }
 
         await mqttManager.publish(resolvedTopic, resolvedJson, { qos, retain });
+        delete this.messageObject;
     },
 
     /**