feat: Add docs test suites for PostgreSQL nested sets behavior, covering cache management, exception handling, extensibility, node operations, and validation. (#76)

Author: terabytesoftw

tests/pgsql/CacheManagementTest.php

@@ -8,6 +8,27 @@
 use yii2\extensions\nestedsets\tests\base\AbstractCacheManagement;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for cache invalidation in nested sets tree behaviors using PostgreSQL.
+ *
+ * Verifies correct cache management, invalidation, and memoization for nested sets tree structures in PostgreSQL
+ * environments, covering node insertions, updates, deletions, and structural changes for both single and multiple tree
+ * models.
+ *
+ * Inherits integration and unit tests from {@see AbstractCacheManagement} to ensure cache lifecycle correctness,
+ * including depth, left, and right attribute handling, and supports both manual and automatic cache invalidation
+ * scenarios.
+ *
+ * Key features.
+ * - Ensures compatibility and correctness of cache logic on the PostgreSQL platform.
+ * - Full coverage of cache population, invalidation, and memoization for nested sets behaviors.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ *
+ * @see AbstractCacheManagement for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('pgsql')]
 final class CacheManagementTest extends AbstractCacheManagement
 {

tests/pgsql/ExceptionHandlingTest.php

@@ -8,6 +8,28 @@
 use yii2\extensions\nestedsets\tests\base\AbstractExceptionHandling;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for exception handling in nested sets tree behaviors using PostgreSQL.
+ *
+ * Verifies correct exception throwing and error messages for invalid node operations and edge cases in nested sets tree
+ * structures on PostgreSQL, covering both single and multiple tree models.
+ *
+ * Inherits unit tests from {@see AbstractExceptionHandling} to ensure robustness of the nested sets behavior by
+ * simulating invalid operations such as appending, inserting, deleting, and making root nodes under unsupported
+ * conditions.
+ *
+ * Key features.
+ * - Ensures error handling consistency for unsupported operations on PostgreSQL.
+ * - Full coverage for invalid append, insert, delete, and makeRoot operations.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ * - Support for both single-tree and multi-tree models.
+ * - Tests for exception messages and types in various edge cases.
+ *
+ * @see AbstractExceptionHandling for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('pgsql')]
 final class ExceptionHandlingTest extends AbstractExceptionHandling
 {

tests/pgsql/ExtensibilityTest.php

@@ -8,6 +8,28 @@
 use yii2\extensions\nestedsets\tests\base\AbstractExtensibility;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for extensibility in nested sets tree behaviors using PostgreSQL.
+ *
+ * Verifies that protected methods in the nested sets behavior remain accessible and customizable for subclassing
+ * scenarios on PostgreSQL, ensuring extensibility for advanced use cases in both single-tree and multi-tree models.
+ *
+ * Inherits unit tests from {@see AbstractExtensibility} to validate the exposure and correct execution of key internal
+ * methods, supporting framework extension and advanced customization in descendant classes.
+ *
+ * Key features.
+ * - Ensures protected methods are accessible for subclass extension.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ * - Supports both single-tree and multi-tree model scenarios.
+ * - Tests before-insert and move operations for extensibility.
+ * - Validates extensibility for root and non-root node operations.
+ * - Verifies correct attribute assignment by protected methods.
+ *
+ * @see AbstractExtensibility for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('pgsql')]
 final class ExtensibilityTest extends AbstractExtensibility
 {

tests/pgsql/MutationTest.php

@@ -8,6 +8,22 @@
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 use yii2\extensions\nestedsets\tests\TestCase;
 
+/**
+ * Test suite for mutation operations in nested sets tree behaviors using PostgreSQL.
+ *
+ * Verifies correct node ordering and tree traversal logic for children queries in PostgreSQL-based nested sets trees.
+ *
+ * Ensures that the children retrieval method respects left/right boundaries and ordering requirements, validating that
+ * tree traversal produces the expected node order after manual updates to the tree structure.
+ *
+ * Key features.
+ * - Ensures correct handling of left/right attribute updates.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ * - Validates children node ordering for tree traversal.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mutation')]
 final class MutationTest extends TestCase
 {

tests/pgsql/NodeAppendTest.php

@@ -8,6 +8,31 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodeAppend;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node append and root promotion in nested sets tree behaviors using PostgreSQL.
+ *
+ * Provides comprehensive unit and integration tests for appending nodes and promoting nodes to root in nested sets tree
+ * structures on PostgreSQL, ensuring correct tree structure, attribute updates, and validation logic for both
+ * single-tree and multi-tree models.
+ *
+ * Inherits tests from {@see AbstractNodeAppend} to validate node append operations, strict validation scenarios, root
+ * promotion, and XML dataset matching after structural changes, covering edge cases such as validation bypass,
+ * attribute refresh requirements, and cross-tree operations.
+ *
+ * Key features.
+ * - Covers both {@see Tree} and {@see MultipleTree} model scenarios.
+ * - Cross-tree append operations for multi-tree models.
+ * - Ensures correct left, right, depth, and tree attribute updates for PostgreSQL.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ * - Root promotion and attribute refresh verification.
+ * - Validation of strict and non-strict append operations.
+ * - XML dataset matching after structural changes.
+ *
+ * @see AbstractNodeAppend for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('pgsql')]
 final class NodeAppendTest extends AbstractNodeAppend
 {

tests/pgsql/NodeDeleteTest.php

@@ -8,6 +8,31 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodeDelete;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node deletion in nested sets tree behaviors using PostgreSQL.
+ *
+ * Provides comprehensive unit tests for node and subtree deletion operations in nested sets tree structures on
+ * PostgreSQL, ensuring correct state transitions, affected row counts, and data integrity after deletions for both
+ * single-tree and multi-tree models.
+ *
+ * Inherits tests from {@see AbstractNodeDelete} to validate node deletion, subtree removals, abort scenarios,
+ * transactional behavior, and update operations on node attributes, covering edge cases and XML dataset consistency
+ * after deletions.
+ *
+ * Key features.
+ * - Covers update operations and affected row count for node attribute changes.
+ * - Ensures correct affected row counts for node and subtree deletions in both {@see Tree} and {@see MultipleTree}
+ *   models.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ * - Tests aborting deletions via `beforeDelete()` and transactional behavior.
+ * - Validates XML dataset consistency after deletions.
+ * - Verifies node state transitions after `deleteWithChildren()` (new record status, old attributes).
+ *
+ * @see AbstractNodeDelete for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('pgsql')]
 final class NodeDeleteTest extends AbstractNodeDelete
 {

tests/pgsql/NodeInsertTest.php

@@ -8,6 +8,30 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodeInsert;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node insertion in nested sets tree behaviors using PostgreSQL.
+ *
+ * Provides comprehensive unit tests for node insertion operations in nested sets tree structures on PostgreSQL,
+ * ensuring correct behavior for inserting nodes before and after targets, with and without validation, and across both
+ * single-tree and multi-tree models.
+ *
+ * Inherits tests from {@see AbstractNodeInsert} to validate insertion logic, strict validation scenarios, cross-tree
+ * insertions, and XML dataset matching after structural changes, covering edge cases such as validation bypass,
+ * attribute refresh requirements, and multi-tree operations.
+ *
+ * Key features.
+ * - Covers both {@see Tree} and {@see MultipleTree} model scenarios.
+ * - Edge case handling for strict validation and cross-tree insertions.
+ * - Ensures correct left, right, depth, and tree attribute updates for PostgreSQL.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ * - Validation of strict and non-strict insert operations.
+ * - XML dataset matching after structural changes.
+ *
+ * @see AbstractNodeInsert for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('pgsql')]
 final class NodeInsertTest extends AbstractNodeInsert
 {

tests/pgsql/NodePrependTest.php

@@ -8,6 +8,29 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodePrepend;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node prepend operations in nested sets tree behaviors using PostgreSQL.
+ *
+ * Provides comprehensive unit and integration tests for prepending nodes in nested sets tree structures on PostgreSQL,
+ * ensuring correct tree structure, attribute updates, and validation logic for both single-tree and multi-tree models.
+ *
+ * Inherits tests from {@see AbstractNodePrepend} to validate node prepend operations, strict validation scenarios, and
+ * XML dataset matching after structural changes, covering edge cases such as validation bypass, attribute refresh
+ * requirements, and cross-tree operations.
+ *
+ * Key features.
+ * - Covers both {@see Tree} and {@see MultipleTree} model scenarios.
+ * - Ensures correct left, right, depth, and tree attribute updates after prepend operations for PostgreSQL.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ * - Tests for prepending new and existing nodes, including cross-tree operations.
+ * - Validation of strict and non-strict prepend operations.
+ * - XML dataset matching after structural changes.
+ *
+ * @see AbstractNodePrepend for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('pgsql')]
 final class NodePrependTest extends AbstractNodePrepend
 {

tests/pgsql/NodeStateTest.php

@@ -8,6 +8,28 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodeState;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node state and relationship in nested sets tree behaviors using PostgreSQL.
+ *
+ * Provides comprehensive unit tests for verifying node state, parent-child relationships, and root/leaf detection in
+ * both single-tree and multi-tree nested sets models on PostgreSQL.
+ *
+ * Inherits tests from {@see AbstractNodeState} to ensure correctness of methods that determine node ancestry, root
+ * status, and leaf status by testing various edge cases and boundary conditions, such as equal left/right values and
+ * ancestor chains.
+ *
+ * Key features.
+ * - Coverage for both {@see Tree} and {@see MultipleTree} model implementations.
+ * - Ensures correct behavior for left/right value manipulations and ancestor checks.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ * - Tests for `isChildOf()` under different ancestor and boundary scenarios.
+ * - Validation of `isRoot()` and `isLeaf()` logic for root, leaf, and intermediate nodes.
+ *
+ * @see AbstractNodeState for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('pgsql')]
 final class NodeStateTest extends AbstractNodeState
 {

tests/pgsql/QueryBehaviorTest.php

@@ -8,6 +8,29 @@
 use yii2\extensions\nestedsets\tests\base\AbstractQueryBehavior;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for query behavior in nested sets tree behaviors using PostgreSQL.
+ *
+ * Provides comprehensive unit tests for query methods related to leaf and root node retrieval, ordering, and behavior
+ * attachment in both single-tree and multi-tree nested sets models on PostgreSQL, ensuring correctness of query methods
+ * such as `leaves()` and `roots()`, including ordering guarantees, SQL generation, and error handling when the behavior
+ * is detached or not attached to the owner.
+ *
+ * Inherits tests from {@see AbstractQueryBehavior} to validate deterministic ordering, correct node retrieval, SQL
+ * structure, and exception handling for query behaviors.
+ *
+ * Key features.
+ * - Ensures deterministic ordering of results by left and tree attributes.
+ * - PostgreSQL-specific configuration for database connection and credentials.
+ * - Tests for correct leaf and root node retrieval in {@see Tree} and {@see MultipleTree} models.
+ * - Validates SQL query structure for ordering requirements.
+ * - Verifies exception handling when the behavior is detached or not attached to the query owner.
+ *
+ * @see AbstractQueryBehavior for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('pgsql')]
 final class QueryBehaviorTest extends AbstractQueryBehavior
 {