feat: update documentation for context

MacPaw · Oct 11, 2024 · 2308e92 · 2308e92
1 parent 6b8c2f7
commit 2308e92
Show file tree

Hide file tree

Showing 8 changed files with 254 additions and 77 deletions.
diff --git a/README.md b/README.md
@@ -1,87 +1,35 @@
-Behat Messenger Context Bundle
-=================================
+# Behat Messenger Context Bundle
 
 | Version | Build Status | Code Coverage |
 |:---------:|:-------------:|:-----:|
 | `master`| [![CI][master Build Status Image]][master Build Status] | [![Coverage Status][master Code Coverage Image]][master Code Coverage] |
 | `develop`| [![CI][develop Build Status Image]][develop Build Status] | [![Coverage Status][develop Code Coverage Image]][develop Code Coverage] |
 
-Installation
-============
+This repository provides custom Behat step definitions for working with Symfony Messenger transports. It includes functionality for checking messages in transports, validating them against expected JSON structures, and working with variable fields.
 
-Step 1: Download the Bundle
-----------------------------------
-Open a command console, enter your project directory and execute:
+## Installation
 
-###  Applications that use Symfony Flex [in progress](https://github.com/MacPaw/BehatRedisContext/issues/2)
+To install the MessengerContext and integrate it with your Behat setup, follow the instructions provided in the [Installation Guide](docs/install.md).
 
-```console
-$ composer require --dev macpaw/behat-messenger-context
-```
+## Available Features
 
-### Applications that don't use Symfony Flex
+### Check a Specific Message in a Transport
+You can verify if a specific message exists in a given transport.
+* Documentation: [Check Transport Message](docs/MessengerContext/check_transport_message.md)
 
-Open a command console, enter your project directory and execute the
-following command to download the latest stable version of this bundle:
+### Check All Messages in a Transport
+Verify if all messages in a given transport match the expected JSON structure.
+* Documentation: [Check All Transport Messages](docs/MessengerContext/check_all_transport_message.md)
 
-```console
-$ composer require --dev macpaw/behat-messenger-context
-```
+### Check Messages with Regular Expressions
+You can use regular expressions to validate messages that contain dynamic or variable data.
+* Documentation for specific message: [Check Transport Message with Regexp](docs/MessengerContext/check_transport_message_regexp.md)
+* Documentation for all messages: [Check All Transport Messages with Regexp](docs/MessengerContext/check_all_transport_message_regexp.md)
 
-This command requires you to have Composer installed globally, as explained
-in the [installation chapter](https://getcomposer.org/doc/00-intro.md)
-of the Composer documentation.
+### Verify Message Count in a Transport
+Ensure that a specific number of messages exist in a given transport.
 
-
-Then, enable the bundle by adding it to the list of registered bundles
-in the `app/AppKernel.php` file of your project:
-
-```php
-<?php
-// app/AppKernel.php
-
-// ...
-class AppKernel extends Kernel
-{
-    public function registerBundles()
-    {
-        $bundles = array(
-            // ...
-            BehatMessengerContext\BehatMessengerContextBundle::class => ['test' => true],
-        );
-
-        // ...
-    }
-
-    // ...
-}
-```
-
-Step 2: Configure Messenger
-=============
-Copying `config/packages/dev/messenger.yaml` and pasting that into `config/packages/test/`. This gives us messenger configuration that will only be used in the test environment. Uncomment the code, and replace sync with in-memory. Do that for both of the transports.
-
-```yaml
-framework:
-    messenger:
-        transports:
-            async: 'in-memory://'
-            async_priority_high: 'in-memory://'
-            ...
-...
-```
-
-
-Step 3: Configure Behat
-=============
-Go to `behat.yml`
-
-```yaml
-...
-  contexts:
-    - BehatMessengerContext\Context\MessengerContext
-...
-```
+* Documentation: [Count Messages in Transport](docs/MessengerContext/count_message_transport.md)
 
 [master Build Status]: https://github.com/macpaw/behat-messenger-context/actions?query=workflow%3ACI+branch%3Amaster
 [master Build Status Image]: https://github.com/macpaw/behat-messenger-context/workflows/CI/badge.svg?branch=master

diff --git a/docs/MessengerContext/check_all_transport_message.md b/docs/MessengerContext/check_all_transport_message.md
@@ -0,0 +1,33 @@
+# Behat Custom Step: Verify All Messages in a Transport
+
+This documentation outlines the purpose and usage of the custom Behat step definition for verifying that all messages in a specific Symfony Messenger transport match a list of expected JSON structures.
+
+## Purpose
+
+This function is designed to validate that all messages in a specific transport (e.g., asynchronous queues) match a given set of expected JSON structures. It is useful in scenarios where you need to ensure that every message in the transport adheres to a specific structure or content format.
+
+## Function Overview
+
+### Signature:
+```gherkin
+Then all transport ":transportName" messages should be JSON:
+"""
+    [
+        {
+            "event": "status_updated",
+            "time": "123123123",
+            "payload": "dqwdwdwdw"
+        },
+        {
+            "event": "order_created",
+            "time": "456456456",
+            "payload": "otherPayload"
+        }
+    ]
+    """
+
+```
+
+### Parameters:
+- `transportName` (string): The name of the transport (e.g., 'async') where the message is expected to be found.
+- `expectedMessage` PyStringNode): A JSON array representing the expected content of all messages that should be present in the transport.
diff --git a/docs/MessengerContext/check_all_transport_message_regexp.md b/docs/MessengerContext/check_all_transport_message_regexp.md
@@ -0,0 +1,41 @@
+# Behat Custom Step: Verify All Messages in Transport with Variable Fields
+
+This documentation outlines the purpose and usage of the custom Behat step definition for verifying that all messages in a specific Symfony Messenger transport match a list of expected JSON structures, while allowing certain fields to vary across the messages.
+## Purpose
+
+This function is designed to validate that all messages in a specific transport (e.g., asynchronous queues) match a given set of expected JSON structures, while allowing certain fields (e.g., timestamps, unique IDs) to have variable values. This is useful in scenarios where specific fields in the messages may differ but the overall structure and format must remain consistent.## Function Overview
+
+### Signature:
+```php
+/**
+ * @Then all transport :transportName messages should be JSON with variable fields :variableFields:
+ */
+public function allTransportMessagesShouldBeJsonWithVariableFields(
+    string $transportName,
+    string $variableFields,
+    PyStringNode $expectedMessageList
+): void
+```
+
+### Parameters:
+- `transportName` (string): The name of the transport (e.g., 'webhook') where the message is expected to be found.
+- `variableFields` (string): A comma-separated list of fields where values may vary and should be compared using regular expressions.
+- `expectedMessage` (PyStringNode): The expected message content in JSON format, where fields marked with `~` in their values will be treated as regular expressions.
+
+```gherkin
+Then all transport ":transportName" messages should be JSON with variable fields ":variableFields":
+"""
+    [
+        {
+            "event": "status_updated",
+            "time": "~^\\d{13}$",
+            "payload": "dqwdwdwdw"
+        },
+        {
+            "event": "order_created",
+            "time": "~^\\d{13}$",
+            "payload": "otherPayload"
+        }
+    ]
+"""
+```
diff --git a/docs/MessengerContext/check_transport_message.md b/docs/MessengerContext/check_transport_message.md
@@ -0,0 +1,26 @@
+
+# Behat Custom Step: Transport JSON Message Assertion
+
+This documentation outlines the purpose and usage of the custom Behat step definition for verifying if a Symfony Messenger transport contains a message with a specific JSON structure.
+
+## Purpose
+
+This function is designed to check if a given transport (such as an asynchronous queue) contains a message that matches a particular JSON structure. It is useful in scenarios where you need to validate that a message was correctly dispatched with the expected content during Behat tests.
+
+## Function Overview
+
+### Signature:
+```gherkin
+Then transport ":transportName" should contain message with JSON:
+    """
+    {
+        "event": "status_updated",
+        "time": "123123123",
+        "payload": "dqwdwdwdw"
+    }
+    """
+```
+
+### Parameters:
+- `transportName` (string): The name of the transport (e.g., 'async') where the message is expected to be found.
+- `expectedMessage` (PyStringNode): The expected message content in JSON format that should be present in the transport.
diff --git a/docs/MessengerContext/check_transport_message_regexp.md b/docs/MessengerContext/check_transport_message_regexp.md
@@ -0,0 +1,36 @@
+
+# Behat Custom Step: Transport JSON Message Assertion with Regexp Fields
+
+This documentation outlines the purpose and usage of the custom Behat step definition for verifying if a Symfony Messenger transport contains a message with a specific JSON structure, using regular expressions to handle dynamic fields.
+## Purpose
+
+This function is designed to check if a given transport (such as an asynchronous queue) contains a message that matches a particular JSON structure, while allowing certain fields to be validated using regular expressions. It is particularly useful when testing messages with dynamic data, such as timestamps, unique identifiers, or payloads, where the exact value cannot be guaranteed.
+## Function Overview
+
+### Signature:
+```php
+/**
+ * @Then transport :transportName should contain message with JSON and variable fields :variableFields:
+ */
+public function transportShouldContainMessageWithJsonAndVariableFields(
+    string $transportName,
+    string $variableFields,
+    PyStringNode $expectedMessage
+): void
+```
+
+### Parameters:
+- `transportName` (string): The name of the transport (e.g., 'webhook') where the message is expected to be found.
+- `variableFields` (string): A comma-separated list of field names where values should be matched using regular expressions.
+- `expectedMessage` (PyStringNode): The expected message content in JSON format, where fields marked with `~` in their values will be treated as regular expressions.
+
+```gherkin
+And transport "webhook" should contain message with JSON and variable fields "time, payload":
+    """
+    {
+        "event": "customer_agreement_status_updated",
+        "time": "~^\\d{13}$",
+        "payload": "~^\\{.*\\}$"
+    }
+    """
+```
diff --git a/docs/MessengerContext/count_message_transport.md b/docs/MessengerContext/count_message_transport.md
@@ -0,0 +1,25 @@
+# Behat Custom Step: Verify Message Count in a Transport
+
+This documentation outlines the purpose and usage of the custom Behat step definition for verifying that a specific number of messages exist in a given Symfony Messenger transport.
+
+## Purpose
+
+This function is designed to check that the number of messages in a specific transport (e.g., asynchronous queues) matches the expected count. It is useful in scenarios where you need to ensure that the correct number of messages have been dispatched into the transport during a Behat test.
+
+## Function Overview
+
+### Signature:
+```php
+/**
+ * @Then there is :expectationMessageCount messages in transport :transportName
+ */
+public function thereIsCountMessagesInTransport(int $expectedMessageCount, string $transportName): void
+```
+
+### Parameters:
+- `expectedMessageCount` (int): The expected number of messages that should be present in the transport.
+- `transportName` (string): The name of the transport (e.g., 'async') where the messages are expected to be found.
+
+```gherkin
+Then there is 1 messages in transport "command"
+```
diff --git a/docs/install.md b/docs/install.md
@@ -0,0 +1,73 @@
+
+# Installation Guide
+
+## Step 1: Install the Bundle
+To begin, navigate to your project directory and use Composer to download the bundle.
+
+### For applications using Symfony Flex:
+Simply run the following command:
+
+```bash
+composer require --dev macpaw/behat-messenger-context
+```
+
+### For applications without Symfony Flex:
+If your project doesn't use Symfony Flex, run the same command:
+
+```bash
+composer require --dev macpaw/behat-messenger-context
+```
+
+Make sure that Composer is installed globally on your machine. If not, refer to the [Composer installation guide](https://getcomposer.org/doc/00-intro.md) for assistance.
+
+Next, you'll need to manually register the bundle in the `AppKernel.php` file. Add the following line to the `registerBundles` method:
+
+```php
+// app/AppKernel.php
+
+class AppKernel extends Kernel
+{
+    public function registerBundles()
+    {
+        $bundles = [
+            // Other bundles
+            BehatMessengerContext\BehatMessengerContextBundle::class => ['test' => true],
+        ];
+    }
+}
+```
+
+## Step 2: Configure Symfony Messenger for Testing
+To ensure your messenger configuration is properly set up for testing, you need to copy the configuration from `config/packages/dev/messenger.yaml` to `config/packages/test/messenger.yaml`. Then, update the configuration to use in-memory transport for testing.
+
+```yaml
+framework:
+    messenger:
+        transports:
+            async: 'in-memory://'
+            async_priority_high: 'in-memory://'
+```
+
+OR in your global config file `config/packages/messenger.yaml`
+```yaml
+framework:
+  messenger:
+    transports:
+      async: 'in-memory://'
+      async_priority_high: 'in-memory://'
+```
+
+This ensures that your tests use an in-memory transport rather than actual services.
+
+## Step 3: Behat Configuration
+In your `behat.yml` file, make sure the Messenger context is registered:
+
+```yaml
+default:
+    suites:
+        default:
+            contexts:
+                - BehatMessengerContext\Context\MessengerContext
+```
+
+This completes the setup for integrating Behat with Symfony Messenger in your project. Now you're ready to run tests with the in-memory transport!
diff --git a/src/Context/MessengerContext.php b/src/Context/MessengerContext.php
@@ -14,15 +14,10 @@
 
 class MessengerContext extends SimilarArray implements Context
 {
-    private ContainerInterface $container;
-    private NormalizerInterface $normalizer;
-
     public function __construct(
-        ContainerInterface $container,
-        NormalizerInterface $normalizer
+        private readonly ContainerInterface $container,
+        private readonly NormalizerInterface $normalizer
     ) {
-        $this->container = $container;
-        $this->normalizer = $normalizer;
     }
 
     /**