8000 Updated traits docs. by AlexSkrypnyk · Pull Request #390 · drevops/behat-steps · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Updated traits docs. #390

New issue

8000 Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 5, 2025
Merged

Updated traits docs. #390

merged 1 commit into from
May 5, 2025

Conversation

AlexSkrypnyk
Copy link
Member
@AlexSkrypnyk AlexSkrypnyk commented May 5, 2025

Summary by CodeRabbit

  • Documentation

    • Expanded and clarified documentation for all Behat step traits with enhanced descriptions, usage notes, and scenario tag controls.
    • Added new traits to documentation: BigPipeTrait, DateTrait, MetatagTrait, OverrideTrait, TestmodeTrait, and WatchdogTrait.
    • Improved structure and comprehensiveness of trait documentation for easier reference.
  • New Features

    • Introduced new traits for BigPipe bypass, relative date handling, meta tag assertions, override behaviors, test mode configuration, and Watchdog error monitoring.
  • Bug Fixes

    • Enhanced validation and error handling for trait documentation comments, including balanced inline code blocks and mandatory descriptions.
  • Tests

    • Added tests for parsing class comments and updated rendering tests to handle nested trait-method structures.
    • Improved test robustness by using partial content assertions and sorting to avoid order-dependent failures.

Copy link
coderabbitai bot commented May 5, 2025

"""

Walkthrough

This change refactors and enhances the documentation extraction, parsing, validation, and rendering for a suite of Drupal Behat step traits. The docs.php script is overhauled to extract and validate trait-level doc comments into a structured, nested format, introducing a new parse_class_comment function. The rendering logic is updated to support markdown-safe trait descriptions and improved formatting. All trait files receive updated, detailed docblock comments describing their purpose, usage, and scenario tags. The steps.md documentation is regenerated to reflect these changes, and the PHPUnit test suite is updated to test the new parsing, rendering, and validation logic, including edge cases and error handling.

Changes

File(s) Change Summary
docs.php Refactored trait info extraction to a nested structure keyed by trait names; added parse_class_comment for doc comment parsing and validation; updated render_info for markdown-safe trait descriptions and list formatting; enhanced validate for new data structure and type safety. Throws exception if trait file is missing from class.
src/BigPipeTrait.php
src/BlockTrait.php
src/ContentBlockTrait.php
src/ContentTrait.php
src/CookieTrait.php
src/DateTrait.php
src/DraggableviewsTrait.php
src/EckTrait.php
src/ElementTrait.php
src/EmailTrait.php
src/FieldTrait.php
src/FileDownloadTrait.php
src/FileTrait.php
src/KeyboardTrait.php
src/LinkTrait.php
src/MediaTrait.php
src/MenuTrait.php
src/MetatagTrait.php
src/OverrideTrait.php
src/ParagraphsTrait.php
src/PathTrait.php
src/ResponseTrait.php
src/SearchApiTrait.php
src/TaxonomyTrait.php
src/TestmodeTrait.php
src/UserTrait.php
src/WaitTrait.php
src/WatchdogTrait.php
Expanded and clarified trait-level docblock comments for all traits, detailing purpose, features, and scenario tags; no functional code changes except a minor whitespace addition in ParagraphsTrait.
steps.md Regenerated and reorganized documentation for all traits, with expanded descriptions, new trait entries, and detailed notes on usage and scenario tags.
tests/phpunit/src/DocsTest.php Added tests for parse_class_comment; updated test data and assertions for new nested info structure; improved robustness of render and validation tests with partial matching and sorting.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant docs.php
    participant TraitFile
    participant steps.md

    User->>docs.php: Run docs.php
    docs.php->>TraitFile: Read trait files from src/
    docs.php->>docs.php: extract_info(class_name)
    docs.php->>docs.php: parse_class_comment(trait_name, docblock)
    docs.php->>docs.php: Validate trait and method info
    docs.php->>steps.md: Write updated documentation with trait descriptions and methods
Loading

Possibly related PRs

  • drevops/behat-steps#383: Adds PHPUnit tests for docs generator functions, directly related to the new and modified parsing and rendering logic in this PR.
  • drevops/behat-steps#378: Updates docs.php with improved validation, error reporting, and markdown output formatting, overlapping in functions modified by this PR.
  • drevops/behat-steps#389: Also modifies extract_info and render_info to include and render trait docblock descriptions, but without the full data restructuring and validation introduced here.

Poem

🐇
In burrows deep, I found each trait,
And polished docs to look first-rate.
With nested notes and markdown bright,
Each feature now described just right.
Hop, skip, and jump through every test—
This rabbit’s docs are now the best!
🌱✨
"""


🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Generate unit testing code for this file.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai generate unit testing code for this file.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and generate unit testing code.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

Copy link
@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 18

📜 Review details

Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between eefd75b and e6a9d91.

📒 Files selected for processing (31)
  • docs.php (7 hunks)
  • src/BigPipeTrait.php (1 hunks)
  • src/BlockTrait.php (1 hunks)
  • src/ContentBlockTrait.php (1 hunks)
  • src/ContentTrait.php (1 hunks)
  • src/CookieTrait.php (1 hunks)
  • src/DateTrait.php (1 hunks)
  • src/DraggableviewsTrait.php (1 hunks)
  • src/EckTrait.php (1 hunks)
  • src/ElementTrait.php (1 hunks)
  • src/EmailTrait.php (1 hunks)
  • src/FieldTrait.php (1 hunks)
  • src/FileDownloadTrait.php (1 hunks)
  • src/FileTrait.php (1 hunks)
  • src/KeyboardTrait.php (1 hunks)
  • src/LinkTrait.php (1 hunks)
  • src/MediaTrait.php (1 hunks)
  • src/MenuTrait.php (1 hunks)
  • src/MetatagTrait.php (1 hunks)
  • src/OverrideTrait.php (1 hunks)
  • src/ParagraphsTrait.php (2 hunks)
  • src/PathTrait.php (1 hunks)
  • src/ResponseTrait.php (1 hunks)
  • src/SearchApiTrait.php (1 hunks)
  • src/TaxonomyTrait.php (1 hunks)
  • src/TestmodeTrait.php (1 hunks)
  • src/UserTrait.php (1 hunks)
  • src/WaitTrait.php (1 hunks)
  • src/WatchdogTrait.php (1 hunks)
  • steps.md (23 hunks)
  • tests/phpunit/src/DocsTest.php (24 hunks)
🧰 Additional context used
🪛 PHPStan (2.0.3)
docs.php

210-210: Parameter #1 $array (non-empty-list) of array_values is already a list, call has no effect.
Because the type is coming from a PHPDoc, you can turn off this check by setting treatPhpDocTypesAsCertain: false in your %configurationFile%.

(arrayValues.list)

🪛 markdownlint-cli2 (0.17.2)
steps.md

38-38: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


8000

39-39: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


39-39: Inline HTML
Element: br

(MD033, no-inline-html)


39-39: Inline HTML
Element: br

(MD033, no-inline-html)


40-40: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


41-41: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


41-41: Inline HTML
Element: br

(MD033, no-inline-html)


41-41: Inline HTML
Element: br

(MD033, no-inline-html)


42-42: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


43-43: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


45-45: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


50-50: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


51-51: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


51-51: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


51-51: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


52-52: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


52-52: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


53-53: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


53-53: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


55-55: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


57-57: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


181-181: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


182-182: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


182-182: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


182-182: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


183-183: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


183-183: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


184-184: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


184-184: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


186-186: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


188-188: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


238-238: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


239-239: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


239-239: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


239-239: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


240-240: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


240-240: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


241-241: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


241-241: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


243-243: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


321-321: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


322-322: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


322-322: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


322-322: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


323-323: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


323-323: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


325-325: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


450-450: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


451-451: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


451-451: Inline HTML
Element: br

(MD033, no-inline-html)


451-451: Inline HTML
Element: br

(MD033, no-inline-html)


452-452: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


453-453: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


453-453: Inline HTML
Element: br

(MD033, no-inline-html)


453-453: Inline HTML
Element: br

(MD033, no-inline-html)


454-454: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


455-455: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


455-455: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


455-455: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


456-456: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


456-456: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


458-458: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


459-459: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


459-459: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


459-459: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


460-460: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


460-460: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


462-462: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


463-463: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


463-463: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


463-463: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


464-464: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


464-464: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


466-466: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


471-471: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


473-473: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


491-491: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


492-492: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


492-492: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


492-492: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


493-493: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


493-493: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


494-494: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


494-494: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


496-496: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


498-498: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


548-548: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


549-549: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


549-549: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


549-549: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


550-550: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


550-550: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


551-551: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


551-551: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


553-553: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


718-718: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


719-719: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


719-719: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


719-719: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


720-720: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


720-720: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


721-721: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


721-721: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


723-723: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


724-724: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


725-725: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


725-725: Inline HTML
Element: br

(MD033, no-inline-html)


725-725: Inline HTML
Element: br

(MD033, no-inline-html)


726-726: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


727-727: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


727-727: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


727-727: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


728-728: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


728-728: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


729-729: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


729-729: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


731-731: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


980-980: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


981-981: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


981-981: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


981-981: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


982-982: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


982-982: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


983-983: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


983-983: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


985-985: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1095-1095: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1096-1096: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1096-1096: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1096-1096: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1097-1097: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1097-1097: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1098-1098: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1098-1098: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1100-1100: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1101-1101: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1102-1102: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1102-1102: Inline HTML
Element: br

(MD033, no-inline-html)


1102-1102: Inline HTML
Element: br

(MD033, no-inline-html)


1103-1103: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1104-1104: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1104-1104: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1104-1104: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1106-1106: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1205-1205: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1206-1206: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1206-1206: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1206-1206: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1207-1207: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1207-1207: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1208-1208: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1208-1208: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1210-1210: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1211-1211: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1213-1213: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1308-1308: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1309-1309: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1309-1309: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1309-1309: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1310-1310: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1310-1310: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1311-1311: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1311-1311: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1313-1313: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1360-1360: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1361-1361: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1361-1361: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1361-1361: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1362-1362: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1362-1362: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1363-1363: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1363-1363: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1365-1365: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1464-1464: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1465-1465: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1465-1465: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1465-1465: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1466-1466: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1466-1466: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1467-1467: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1467-1467: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1468-1468: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1468-1468: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1470-1470: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1472-1472: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1523-1523: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1524-1524: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1524-1524: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1524-1524: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1525-1525: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1525-1525: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1526-1526: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1526-1526: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1527-1527: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1527-1527: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1529-1529: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1531-1531: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1584-1584: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1585-1585: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1585-1585: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1585-1585: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1587-1587: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1592-1592: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1593-1593: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1593-1593: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1593-1593: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1594-1594: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1594-1594: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1596-1596: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1597-1597: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1598-1598: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1599-1599: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1600-1600: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1601-1601: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1603-1603: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1608-1608: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1609-1609: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1609-1609: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1609-1609: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1610-1610: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1610-1610: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1611-1611: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1611-1611: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1612-1612: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1612-1612: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1614-1614: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1616-1616: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1635-1635: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1636-1636: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1636-1636: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1636-1636: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1637-1637: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1637-1637: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1639-1639: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1676-1676: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1677-1677: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1677-1677: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1677-1677: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1679-1679: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1724-1724: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1725-1725: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1725-1725: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1725-1725: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1726-1726: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1726-1726: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1728-1728: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1754-1754: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1755-1755: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1755-1755: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1755-1755: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1756-1756: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1756-1756: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1757-1757: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1757-1757: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1759-1759: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1836-1836: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1837-1837: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1837-1837: Inline HTML
Element: br

(MD033, no-inline-html)


1837-1837: Inline HTML
Element: br

(MD033, no-inline-html)


1838-1838: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1839-1839: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1840-1840: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1840-1840: Inline HTML
Element: br

(MD033, no-inline-html)


1840-1840: Inline HTML
Element: br

(MD033, no-inline-html)


1841-1841: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1842-1842: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1842-1842: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1842-1842: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1844-1844: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


1849-1849: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1850-1850: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1850-1850: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1850-1850: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


1851-1851: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1851-1851: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1852-1852: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1852-1852: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1853-1853: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1853-1853: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1854-1854: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


1854-1854: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


1856-1856: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


2033-2033: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2035-2035: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)


2062-2062: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2063-2063: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


2063-2063: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2063-2063: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


2064-2064: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


2064-2064: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2065-2065: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


2065-2065: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2067-2067: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2068-2068: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2069-2069: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2069-2069: Inline HTML
Element: br

(MD033, no-inline-html)


2069-2069: Inline HTML
Element: br

(MD033, no-inline-html)


2070-2070: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2071-2071: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


2071-2071: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2071-2071: Lists should be surrounded by blank lines
null

(MD032, blanks-around-lists)


2072-2072: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)


2072-2072: Multiple spaces after blockquote symbol
null

(MD027, no-multiple-space-blockquote)


2074-2074: Multiple consecutive blank lines
Expected: 1; Actual: 2

(MD012, no-multiple-blanks)

🪛 LanguageTool
steps.md

[uncategorized] ~460-~460: Loose punctuation mark.
Context: ...e parsed by strtotime(). > - FORMAT: date() format for additional processi...

(UNLIKELY_OPENING_PUNCTUATION)


[grammar] ~463-~463: This phrase is duplicated. You should probably use “converted to” only once.
Context: ... > Examples: > - [relative:-1 day] converted to 1893456000 > - [relative:-1 day#Y-m-d] converted to 2017-11-5 ## DraggableviewsTrait [...

(PHRASE_REPETITION)

🔇 Additional comments (25)
src/ContentBlockTrait.php (1)

14-20: Well-defined docblock enhances clarity. The revised docblock clearly enumerates the trait's capabilities—defining, editing, verifying, and cleaning up block content—and documents the skip tag mechanism. Great improvement.

src/BigPipeTrait.php (1)

14-19: Clear and explicit trait documentation. The updated docblock succinctly explains how to activate and skip the BigPipe behavior using scenario tags, improving on the previous generic description.

src/SearchApiTrait.php (1)

10-14: Well-scoped docblock improves readability. The updated comment now explicitly lists the main operations (adding content to the index and running the indexer), making the trait’s purpose clearer.

src/FileTrait.php (1)

16-24: Comprehensive docblock accurately reflects functionality. The enhanced documentation now clearly outlines file creation, verification, cleanup steps, and skip-tag controls.

src/TestmodeTrait.php (1)

12-19: Focused trait description enhances clarity. The revised docblock concisely explains how the Testmode module is configured and controlled via scenario tags.

src/MetatagTrait.php (1)

10-12: Excellent improvement to the trait docblock.
The summary and bullet clearly describe the intent and behavior of the MetatagTrait, improving readability and discoverability of its capabilities.

src/KeyboardTrait.php (1)

11-15: Approve documentation clarity
The updated summary and bullet points comprehensively describe the keyboard interaction capabilities, including special keys, navigation, and element targeting. Well done.

src/PathTrait.php (1)

8-11: Approve class docblock improvements

The updated docblock clearly describes the trait’s capabilities with concise bullet points and improved specificity. The description and list items are grammatically correct and consistent.

src/LinkTrait.php (1)

8-12: Approve enhanced trait documentation

The revised docblock provides a clear summary of link-related assertions and supports the new structured documentation format. The bullet points are informative and well-formatted.

src/UserTrait.php (1)

13-20: Approve detailed user management docblock

The updated class docblock now accurately lists the trait’s user management responsibilities—account creation, role/permission handling, profile actions, and status assertions—enhancing clarity and aligning with the structured docs.

src/CookieTrait.php (1)

8-11: Approve refined cookie trait documentation

The docblock now precisely conveys the trait’s capabilities, including matching strategies and driver compatibility, using clear bullet points.

src/OverrideTrait.php (2)

10-13: Clearer docblock summary and bullet list for OverrideTrait
The updated docblock now concisely highlights the two primary overrides (automated entity deletion and improved anonymous user handling) with a well-structured bullet list.


18-20: Enhanced caution instructions for step definition conflicts
The caution section clearly instructs users how to resolve missing or duplicated step definitions by copying trait contents and including Drupal Extension definitions directly.

src/ContentTrait.php (1)

13-17: Improved docblock for ContentTrait responsibilities
The docblock now provides a concise summary and a structured bullet list covering node creation, navigation, editorial workflows, and scheduled publishing.

src/BlockTrait.php (2)

13-17: Expanded docblock summary and capabilities for BlockTrait
The documentation now clearly lists block creation, placement, rendering verification, and automatic cleanup responsibilities.


19-19: Added skip-tag guidance for automatic cleanup
The new line explains how to bypass automatic block teardown using the @behat-steps-skip:blockAfterScenario tag.

src/FieldTrait.php (1)

13-17: Detailed docblock for form field manipulation and verification
The updated comment now highlights setting values, assertions on existence and state, and support for specialized widgets like color pickers and WYSIWYG editors.

src/ElementTrait.php (1)

8-12: Refined docblock outlining ElementTrait features
The revised summary and bullet points succinctly describe element visibility/assertions, JS interactions, and scrolling/confirmation handling.

src/FileDownloadTrait.php (1)

16-27: Doc-block bullets lack consistent punctuation & style

The newly-added list items are clear, but some bullets end with periods while others do not. For consistency with PSR-5 and to keep the generated Markdown neat, consider either finishing every bullet with a period or omitting periods everywhere.

[ suggest_nitpick ]

src/ParagraphsTrait.php (2)

14-22: Minor doc-block style polish

Same as in FileDownloadTrait – the bulleted list mixes terminal punctuation (line 20 has a period, lines 16-19 do not). Aligning them will make the generated docs look more professional.

[ suggest_nitpick ]


45-45: Extra blank line is harmless

The extra blank line after the foreach improves readability and does not affect behaviour. 👍

[ approve_code_changes ]

src/EmailTrait.php (1)

14-27: Uniform punctuation in bullet list

For the sake of consistency through the project’s auto-generated docs, consider giving each bullet either a trailing period or none at all (currently only the last one omits it).

[ suggest_nitpick ]

tests/phpunit/src/DocsTest.php (1)

416-425: Use DIRECTORY_SEPARATOR to build paths

The test now hard-codes forward slashes when it builds the stub paths (src/%s.php, tests/behat/features/%s.feature).
On Windows this still works most of the time, but relying on DIRECTORY_SEPARATOR (or implode()) guarantees portability.

-      $src_file = sprintf('src/%s.php', $trait);
-      $src_file_path = $base_path . DIRECTORY_SEPARATOR . $src_file;
+      $src_file_path = $base_path .
+        DIRECTORY_SEPARATOR . 'src' .
+        DIRECTORY_SEPARATOR . $trait . '.php';

Do the same for $example_file_path.

[ suggest_nitpick ]

docs.php (2)

239-242: Inline-code fence balance check may give false positives

substr_count($full_description, '')` counts every back-tick, including those
inside triple-back-tick fences (```), which appear three at a time.
For long descriptions using fenced blocks this can report an error even when the
code blocks are correct.

Consider counting ` occurrences only outside triple fences or using a small
state machine.


480-536: Undefined index access in validate()

Even after the earlier fix, $method does not guarantee keys like
'description' or 'example'. Access is guarded with is_string() but that
still triggers a notice if the key is absent.

Wrap the access with isset() first, e.g.

$method['description'] = isset($method['description']) && is_string($method['description'])
  ? $method['description']
  : '';

or normalise the structure once in extract_info() and rely on it afterwards.

* - Create, edit, and verify block_content entities by type and description.
* - Automatically clean up created entities after scenario completion.
*
* Skip processing with tag: `@behat-steps-skip:contentBlockAfterScenario`
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Nit: Add trailing period to bullet. The “Skip processing with tag” list item is missing a period at the end for consistency with the other bullets.

* Search API-related steps.
*
* @package DrevOps\BehatSteps
* - Add content to an index
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Nit: Add trailing period to bullet. The first list item (“Add content to an index”) should end with a period to match the punctuation style of the second item.

*
* @package DrevOps\BehatSteps
* Skip processing with tags: `@behat-steps-skip:fileBeforeScenario` or
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Nit: Add trailing period to bullet. The “Skip processing with tags” list item is missing a period for consistency with other bullet points.

* Include this trait in your FeatureContext.php file to enable Testmode's test
* mode for tests tagged with 'testmode'.
* Special tags:
* - `@testmode` - enable for scenario
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Nit: Add trailing period to nested bullet. The nested list item (“@testmode - enable for scenario”) should end with a period to maintain consistent punctuation.

8000 docs.php
Comment on lines +205 to +214
if (empty($comment)) {
throw new \Exception(sprintf('Class comment for %s is empty', $trait_name));
}

$comment = preg_replace('#^/\*\*|^\s*\*\/$#m', '', $comment);
$lines = array_values(
array_map(static fn($l): string => ltrim($l, " *\t"), explode(PHP_EOL, (string) $comment))
);

// Remove first and last empty lines.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Micro-optimisation & php-stan noise – redundant array_values()

array_map() already produces a numerically indexed array; the subsequent
array_values() call is therefore a no-op and flagged by PHPStan.

-  $lines = array_values(
-    array_map(static fn($l): string => ltrim($l, " *\t"), explode(PHP_EOL, (string) $comment))
-  );
+  $lines = array_map(
+    static fn($l): string => ltrim($l, " *\t"),
+    explode(PHP_EOL, (string) $comment)
+  );

Removing it keeps the function tight and silences the linters.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
if (empty($comment)) {
throw new \Exception(sprintf('Class comment for %s is empty', $trait_name));
}
$comment = preg_replace('#^/\*\*|^\s*\*\/$#m', '', $comment);
$lines = array_values(
array_map(static fn($l): string => ltrim($l, " *\t"), explode(PHP_EOL, (string) $comment))
);
// Remove first and last empty lines.
if (empty($comment)) {
throw new \Exception(sprintf('Class comment for %s is empty', $trait_name));
}
$comment = preg_replace('#^/\*\*|^\s*\*\/$#m', '', $comment);
$lines = array_map(
static fn($l): string => ltrim($l, " *\t"),
explode(PHP_EOL, (string) $comment)
);
// Remove first and last empty lines.
🧰 Tools
🪛 PHPStan (2.0.3)

210-210: Parameter #1 $array (non-empty-list) of array_values is already a list, call has no effect.
Because the type is coming from a PHPDoc, you can turn off this check by setting treatPhpDocTypesAsCertain: false in your %configurationFile%.

(arrayValues.list)

Copy link
codecov bot commented May 5, 2025

Codecov Report

Attention: Patch coverage is 66.66667% with 28 lines in your changes missing coverage. Please review.

Project coverage is 80.71%. Comparing base (eefd75b) to head (30108fd).
Report is 1 commits behind head on 3.x.

Files with missing lines Patch % Lines
docs.php 66.66% 28 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##              3.x     #390      +/-   ##
==========================================
+ Coverage   79.70%   80.71%   +1.00%     
==========================================
  Files          29       29              
  Lines        1902     1913      +11     
==========================================
+ Hits         1516     1544      +28     
+ Misses        386      369      -17     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@AlexSkrypnyk AlexSkrypnyk force-pushed the feature/update-trait-docs branch from e6a9d91 to 445c08b Compare May 5, 2025 00:38
Copy link
@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 9

🔭 Outside diff range comments (1)
tests/phpunit/src/DocsTest.php (1)

415-425: 🧹 Nitpick (assertive)

Potential race condition / leftover artefacts in tmp directory

testRenderInfo() creates real directories and files under static::$tmp but
never cleans them up. When the test suite is run in parallel or re-run without
sys_get_temp_dir() being purged, stale files can make later assertions pass
or fail incorrectly.

Adding a tearDown() that recursively removes the created paths will keep the
tests hermetic.

♻️ Duplicate comments (12)
src/SearchApiTrait.php (1)

12-12: 🧹 Nitpick (assertive)

Add trailing period for consistency.

The first list item should end with a period to match the punctuation style of the second item.

- - Add content to an index
+ - Add content to an index.
src/FileTrait.php (1)

22-23: Nit: Add trailing period to skip processing entry.
The "Skip processing with tags" line lacks a trailing period, which is inconsistent with the other bullet items. Please append a period.

src/WatchdogTrait.php (1)

11-24: 🧹 Nitpick (assertive)

Comprehensive and clear trait documentation

The updated docblock provides excellent detail about the trait's purpose and functionality. It clearly explains what the trait does, how it can be configured, and the special tags that control its behavior.

However, there's one small improvement from a previous review that wasn't addressed:

  • Consider replacing "Skip processing with tags:" with "Skip hooks with tags:" to more accurately reflect the hook-based behavior.
src/WaitTrait.php (1)

9-11: Concise trait documentation with imperative verb

The docblock now uses the imperative form "Wait for" instead of "Waiting for" as suggested in a previous review, making it consistent with other traits.

src/ResponseTrait.php (1)

7-11: 🛠️ Refactor suggestion

Align summary and bullets
The class-level docblock mentions both "status code and header checks" but the bullet list only covers headers. Please add a bullet for status code assertions or adjust the summary accordingly.

src/TaxonomyTrait.php (1)

11-15: 🧹 Nitpick (assertive)

Consistent punctuation in bullet list
The second bullet is missing a terminal period. For consistency, please add one.

src/DraggableviewsTrait.php (1)

14-15: 🧹 Nitpick (assertive)

Add detailed bullet list for clarity
Other traits include a bullet list of capabilities; please expand this docblock to enumerate the core steps (e.g., removing old ordering entries, inserting new order, invalidating cache tags).

src/TestmodeTrait.php (1)

17-19: 🧹 Nitpick (assertive)

Nit: Add trailing period to nested bullet.

The nested list item (“@testmode - enable for scenario”) should end with a period to maintain consistent punctuation.

- * - `@testmode` - enable for scenario
+ * - `@testmode` - enable for scenario.
src/MenuTrait.php (1)

21-21: 🧹 Nitpick (assertive)

Nit: Clarify skip behavior wording.

The line currently reads:

* Skip processing with tag: `@behat-steps-skip:menuAfterScenario`

Consider specifying cleanup semantics to reflect AfterScenario behavior:

- * Skip processing with tag: `@behat-steps-skip:menuAfterScenari
6D40
o`
+ * Skip cleanup of created menus and links with tag: `@behat-steps-skip:menuAfterScenario`.
docs.php (3)

210-213: Redundant array_values() – micro-optimisation & static-analysis noise
The result of array_map() is already a numerically indexed list; wrapping it
in array_values() has no effect and triggers PHPStan’s arrayValues.list
warning.

-  $lines = array_values(
-    array_map(static fn($l): string => ltrim($l, " *\t"), explode(PHP_EOL, (string) $comment))
-  );
+  $lines = array_map(
+    static fn($l): string => ltrim($l, " *\t"),
+    explode(PHP_EOL, (string) $comment)
+  );

390-414: Markdown formatting produces <br/><br/> and double-space block-quotes

The manual insertion of <br/><br/> inside the block-quote renders fine on
GitHub but provokes a storm of markdownlint (MD033, MD027, etc.) warnings
and hampers downstream tooling.

If lint cleanliness matters, consider:

  1. replacing the HTML breaks with an empty quoted line (>);
  2. adding blank lines before / after list items inside the quote.

No functional impact, just tidier output.


452-459: Unused [description] placeholder in the template

strtr() still receives a [description] replacement, yet the placeholder
doesn’t appear in the $template, so the substitution is a no-op and confuses
future maintainers.

Either expose the description in the collapsible header or remove the mapping
entry.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Lite

📥 Commits

Reviewing files that changed from the base of the PR and between e6a9d91 and 445c08b.

📒 Files selected for processing (31)
  • docs.php (6 hunks)
  • src/BigPipeTrait.php (1 hunks)
  • src/BlockTrait.php (1 hunks)
  • src/ContentBlockTrait.php (1 hunks)
  • src/ContentTrait.php (1 hunks)
  • src/CookieTrait.php (1 hunks)
  • src/DateTrait.php (1 hunks)
  • src/DraggableviewsTrait.php (1 hunks)
  • src/EckTrait.php (1 hunks)
  • src/ElementTrait.php (1 hunks)
  • src/EmailTrait.php (1 hunks)
  • src/FieldTrait.php (1 hunks)
  • src/FileDownloadTrait.php (1 hunks)
  • src/FileTrait.php (1 hunks)
  • src/KeyboardTrait.php (1 hunks)
  • src/LinkTrait.php (1 hunks)
  • src/MediaTrait.php (1 hunks)
  • src/MenuTrait.php (1 hunks)
  • src/MetatagTrait.php (1 hunks)
  • src/OverrideTrait.php (1 hunks)
  • src/ParagraphsTrait.php (2 hunks)
  • src/PathTrait.php (1 hunks)
  • src/ResponseTrait.php (1 hunks)
  • src/SearchApiTrait.php (1 hunks)
  • src/TaxonomyTrait.php (1 hunks)
  • src/TestmodeTrait.php (1 hunks)
  • src/UserTrait.php (1 hunks)
  • src/WaitTrait.php (1 hunks)
  • src/WatchdogTrait.php (1 hunks)
  • steps.md (23 hunks)
  • tests/phpunit/src/DocsTest.php (24 hunks)
🔇 Additional comments (16)
src/CookieTrait.php (1)

7-12: Great documentation improvement!

The revised docblock offers much clearer information about the trait's capabilities and compatibility. The specificity about asserting cookie existence with exact/partial matching and driver compatibility provides valuable context for users.

src/DateTrait.php (1)

9-25: Excellent documentation enhancement!

The revised docblock provides comprehensive information about the trait's functionality with well-structured format specifications, parameter explanations, and practical examples. This makes the trait's usage much clearer for developers.

src/OverrideTrait.php (1)

9-21: Well-improved trait documentation!

The revised docblock clearly communicates both the specific behaviors being overridden and provides more precise instructions for handling potential step definition conflicts. This dual focus on functionality and troubleshooting makes the trait documentation much more useful.

src/SearchApiTrait.php (1)

9-14: Improved trait description!

The revised docblock provides a more precise description of the trait's purpose and clearly lists its specific capabilities, making it more helpful for developers.

src/ParagraphsTrait.php (2)

13-22: Well-structured trait documentation

The updated docblock provides a clear overview of the trait's capabilities with paragraph entities. The bullet points effectively communicate the main functionalities.


45-45: Improved code readability

The added blank line improves readability by separating the loop from the array reset operation.

src/MetatagTrait.php (1)

9-13: Clear and focused trait documentation

The updated docblock provides a precise description of the trait's purpose, focusing on asserting meta tags in the page markup with proper attribute handling.

src/KeyboardTrait.php (1)

10-16: Docblock clarity improved
The updated summary and bullet points clearly describe the trait’s keyboard interaction capabilities and are formatted consistently.

src/ContentBlockTrait.php (1)

14-21: Docblock enhancement for ContentBlockTrait
Good improvement: the doc comment now enumerates the trait’s capabilities and clearly documents the skip tag.

src/PathTrait.php (1)

7-12: Documentation improvements look good.

The updated docblock provides a clearer and more specific description of what the trait does, with bullet points highlighting the key capabilities. This is a good improvement over the previous generic description.

src/LinkTrait.php (1)

7-13: Improved trait description with clear capability breakdown.

The updated docblock effectively communicates the trait's purpose with a structured list of capabilities. This makes it much easier for developers to understand what functionality the trait provides at a glance.

src/BigPipeTrait.php (1)

13-20: Good documentation enhancement with activation instructions.

The updated docblock clearly explains the trait's purpose and includes valuable usage information about activation and skip tags. This makes the trait more accessible to developers who need to control BigPipe behavior in their tests.

src/ContentTrait.php (1)

12-18: Well-structured documentation with comprehensive capability listing.

The updated docblock transforms a simple one-line description into a detailed explanation of the trait's functionality. The bullet-point format clearly communicates the trait's capabilities, making it easier for developers to understand its purpose and features.

src/BlockTrait.php (1)

12-20: Excellent documentation with clear functionality and usage notes.

The updated docblock provides a comprehensive description of the trait's purpose with well-structured bullet points explaining key capabilities. The addition of automatic cleanup information and skip tag documentation is particularly helpful for users implementing test scenarios.

src/FieldTrait.php (1)

13-18: Well-structured docblock update.

The class docblock now provides a clear summary and consistent bullet list describing the trait's capabilities. Punctuation and formatting are correct.

src/ElementTrait.php (1)

8-12: Well-structured docblock with clear bullets.

The updated class docblock succinctly describes the trait's responsibilities with consistent bullet formatting and correct punctuation.

Comment on lines +13 to +19
* Manage Drupal users with role and permission assignments.
*
* Provides functionality for creating and managing Drupal users,
* assigning roles, and handling user authentication.
*
* @package DrevOps\BehatSteps
* - Create user accounts
* - Create user roles
* - Visit user profile pages for editing and deletion.
* - Assert user roles and permissions.
* - Assert user account status (active/inactive).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Ensure consistency in bullet punctuation.
The first two bullet items ("Create user accounts" and "Create user roles") are missing trailing periods, while the subsequent bullets end with periods. For consistency, add periods to all bullet items (or remove them from the others).

Comment on lines +18 to 19
* Skip processing with tag: `@behat-steps-skip:eckAfterScenario`
*/
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Format skip processing entry as bullet with trailing period.
The "Skip processing with tag" line isn't formatted as a bullet like the preceding list and is missing a trailing period. Consider updating it to:

- * Skip processing with tag: `@behat-steps-skip:eckAfterScenario`
+ * - Skip processing with tag: `@behat-steps-skip:eckAfterScenario`.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
* Skip processing with tag: `@behat-steps-skip:eckAfterScenario`
*/
* - Skip processing with tag: `@behat-steps-skip:eckAfterScenario`.
*/

Comment on lines +22 to +23
* Skip processing with tags: `@behat-steps-skip:fileDownloadBeforeScenario` or
* `@behat-steps-skip:fileDownloadAfterScenario`
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Format skip processing entry as bullet with trailing period.
The "Skip processing with tags" line is not part of the bullet list and lacks a trailing period. For consistent documentation, consider:

- * Skip processing with tags: `@behat-steps-skip:fileDownloadBeforeScenario` or
- * `@behat-steps-skip:fileDownloadAfterScenario`
+ * - Skip processing with tags: `@behat-steps-skip:fileDownloadBeforeScenario` or `@behat-steps-skip:fileDownloadAfterScenario`.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
* Skip processing with tags: `@behat-steps-skip:fileDownloadBeforeScenario` or
* `@behat-steps-skip:fileDownloadAfterScenario`
* - Skip processing with tags: `@behat-steps-skip:fileDownloadBeforeScenario` or `@behat-steps-skip:fileDownloadAfterScenario`.

F438
* - Assert media browser functionality and edit media entity fields.
* - Support for multiple media types with field value expansion handling.
* - Automatically clean up created entities after scenario completion.
*
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Format skip processing entry as bullet with trailing period.
The "Skip processing with tag" line isn't formatted as a bullet like the list above and is missing a trailing period. Consider:

- * Skip processing with tag: `@behat-steps-skip:mediaAfterScenario`
+ * - Skip processing with tag: `@behat-steps-skip:mediaAfterScenario`.

Committable suggestion skipped: line range outside the PR's diff.

Comment on lines +20 to 27
* Skip processing with tags: `@behat-steps-skip:emailBeforeScenario` or
* `@behat-steps-skip:emailAfterScenario`
*
* Special tags:
* - `@email` - enable email tracking using a default handler
* - `@email:{type}` - enable email tracking using a `{type}` handler
* - `@debug` (enable detailed logs)
*/
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Nit: Ensure consistent trailing punctuation in bullets.

Several bullets in this docblock lack periods at the end. For consistency, add periods:

- * Skip processing with tags: `@behat-steps-skip:emailBeforeScenario` or
- * `@behat-steps-skip:emailAfterScenario`
+ * Skip processing with tags: `@behat-steps-skip:emailBeforeScenario` or `@behat-steps-skip:emailAfterScenario`.

- * - `@email` - enable email tracking using a default handler
- * - `@email:{type}` - enable email tracking using a `{type}` handler
- * - `@debug` (enable detailed logs)
+ * - `@email` - enable email tracking using a default handler.
+ * - `@email:{type}` - enable email tracking using a `{type}` handler.
+ * - `@debug` - enable detailed logs.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
* Skip processing with tags: `@behat-steps-skip:emailBeforeScenario` or
* `@behat-steps-skip:emailAfterScenario`
*
* Special tags:
* - `@email` - enable email tracking using a default handler
* - `@email:{type}` - enable email tracking using a `{type}` handler
* - `@debug` (enable detailed logs)
*/
* Skip processing with tags: `@behat-steps-skip:emailBeforeScenario` or `@behat-steps-skip:emailAfterScenario`.
*
* Special tags:
* - `@email` - enable email tracking using a default handler.
* - `@email:{type}` - enable email tracking using a `{type}` handler.
* - `@debug` - enable detailed logs.
*/

Comment on lines +186 to +188
if (!empty($traits_files)) {
throw new \Exception(sprintf('The following traits were not found in the class: %s', implode(', ', $traits_files)));
}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Edge case: Class files that are not traits will still trip the safeguard

Even after filtering for “*.php”, any helper classes that live in src/
(e.g. DTOs, abstract classes) will still be interpreted as traits missing from
FeatureContext, and the script will abort.
Consider either:

  • limiting the directory scan to filenames that actually end with Trait.php; or
  • deriving the expected list from FeatureContextTrait reflection itself.

This makes the check semantically correct and removes maintenance friction when
new non-trait utilities are added.

Comment on lines +103 to 116
// Collect all traits in the src directory to validate that they all present
// in the $class_name class.
$traits_path = $base_path . DIRECTORY_SEPARATOR . 'src';
$traits_files = [];
if (is_dir($traits_path)) {
$files = scandir($traits_path) ?: [];
foreach ($files as $file) {
if (is_file($traits_path . DIRECTORY_SEPARATOR . $file)) {
$traits_files[] = basename($file, '.php');
}
}
sort($traits_files);
}

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Filter only PHP trait files to avoid false-positive “missing trait” exceptions

$traits_files currently collects every regular file in src/, then strips the
.php extension. If the directory happens to contain non-PHP artefacts
(README, .md, .bak, etc.) they will be treated as traits and the final
check (throw new \Exception(...)) will abort the generator even though the
code base is perfectly valid.

-      if (is_file($traits_path . DIRECTORY_SEPARATOR . $file)) {
-        $traits_files[] = basename($file, '.php');
+      if (is_file($traits_path . DIRECTORY_SEPARATOR . $file) &&
+          str_ends_with($file, '.php')) {
+        $traits_files[] = basename($file, '.php');
       }

A simple extension check prevents the false alarm while keeping the safety net
for genuinely missing trait registrations.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
// Collect all traits in the src directory to validate that they all present
// in the $class_name class.
$traits_path = $base_path . DIRECTORY_SEPARATOR . 'src';
$traits_files = [];
if (is_dir($traits_path)) {
$files = scandir($traits_path) ?: [];
foreach ($files as $file) {
if (is_file($traits_path . DIRECTORY_SEPARATOR . $file)) {
$traits_files[] = basename($file, '.php');
}
}
sort($traits_files);
}
// Collect all traits in the src directory to validate that they all present
// in the $class_name class.
$traits_path = $base_path . DIRECTORY_SEPARATOR . 'src';
$traits_files = [];
if (is_dir($traits_path)) {
$files = scandir($traits_path) ?: [];
foreach ($files as $file) {
if (is_file($traits_path . DIRECTORY_SEPARATOR . $file) &&
str_ends_with($file, '.php')) {
$traits_files[] = basename($file, '.php');
}
}
sort($traits_files);
}

Comment on lines +38 to +44
> Bypass Drupal BigPipe when rendering pages.
> <br/><br/>
> Activated by adding `@big_pipe` tag to the scenario.
> <br/><br/>
> Skip processing with tags: `@behat-steps-skip:bigPipeBeforeScenario` or
> `@behat-steps-skip:bigPipeBeforeStep`.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Unexpected inline HTML & double-space block-quotes

The regenerated docs insert <br/><br/> tags and two spaces after each >
character. While this is acceptable for GitHub’s renderer, it violates several
common markdown-lint rules (MD033, MD027) and may hinder other renderers.

If linting is part of CI, consider switching to blank quoted lines (>) and
single-space prefixes.

@AlexSkrypnyk AlexSkrypnyk force-pushed the feature/update-trait-docs branch from 445c08b to 30108fd Compare May 5, 2025 00:50
Copy link
@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

♻️ Duplicate comments (23)
src/TaxonomyTrait.php (1)

11-15: Consistent punctuation in bullet list
The second bullet is missing a terminal period. For consistency with the other items, please add a period at the end of “Navigate to term pages.”

src/SearchApiTrait.php (1)

10-13: 🧹 Nitpick (assertive)

Missing trailing period for consistency.

The first bullet point on line 12 "Add content to an index" is missing a trailing period, while the second bullet point on line 13 has one. For consistency, add a period to the first item.

 /**
  * Assert Drupal Search API with index and query operations.
  *
- * - Add content to an index
+ * - Add content to an index.
  * - Run indexing for a specific number of items.
  */
src/UserTrait.php (1)

15-19: Ensure consistency in bullet punctuation.

The first two bullet items ("Create user accounts" and "Create user roles") are missing trailing periods, while the subsequent bullets end with periods. For consistency, add periods to all bullet items (or remove them from the others).

src/TestmodeTrait.php (1)

18-18: Nit: Add trailing period to nested bullet.

The list item "@testmode - enable for scenario" should end with a period to maintain consistent punctuation with other documentation.

src/MenuTrait.php (1)

21-21: Nit: Refine skip phrasing in docblock

The summary bullet "Skip processing with tag: @behat-steps-skip:menuAfterScenario" may be clearer as "Skip cleanup with tag: @behat-steps-skip:menuAfterScenario" to match the actual AfterScenario behavior.

src/EmailTrait.php (1)

13-27: 🧹 Nitpick (assertive)

Comprehensive trait documentation, but inconsistent formatting.

The enhanced documentation clearly describes the trait's capabilities and tag-based controls. However, there's inconsistent formatting in the bullet points - some lack trailing periods.

 * Skip processing with tags: `@behat-steps-skip:emailBeforeScenario` or
 * `@behat-steps-skip:emailAfterScenario`
+* Skip processing with tags: `@behat-steps-skip:emailBeforeScenario` or `@behat-steps-skip:emailAfterScenario`.

 * - `@email` - enable email tracking using a default handler
 * - `@email:{type}` - enable email tracking using a `{type}` handler
 * - `@debug` (enable detailed logs)
+* - `@email` - enable email tracking using a default handler.
+* - `@email:{type}` - enable email tracking using a `{type}` handler.
+* - `@debug` - enable detailed logs.
src/ResponseTrait.php (1)

8-10: 🧹 Nitpick (assertive)

Add bullet point for status code assertions.

The docblock summary mentions both status code and header checks, but the bullet list only includes header assertions. To maintain consistency between the summary and bullet points, add a status code assertion bullet.

 * Verify HTTP responses with status code and header checks.
 *
 * - Assert HTTP header presence and values.
+* - Assert HTTP response status codes.
src/ContentBlockTrait.php (1)

20-20: 🧹 Nitpick (assertive)

Add trailing period to skip processing bullet.

For consistency with the other bullet points in the documentation, the last bullet point should end with a period.

- * Skip processing with tag: `@behat-steps-skip:contentBlockAfterScenario`
+ * Skip processing with tag: `@behat-steps-skip:contentBlockAfterScenario`.
src/EckTrait.php (1)

12-19: 🧹 Nitpick (assertive)

Format skip processing entry as bullet with trailing period.

The documentation has been greatly improved with clearer descriptions and bullet points. However, the "Skip processing with tag" line isn't formatted consistently with the preceding list and is missing a trailing period.

- * Skip processing with tag: `@behat-steps-skip:eckAfterScenario`
+ * - Skip processing with tag: `@behat-steps-skip:eckAfterScenario`.
src/FileDownloadTrait.php (1)

22-23: 🧹 Nitpick (assertive)

Bullet still misses terminating period – duplicates previous feedback

The “Skip processing with tags” entry is now part of the list (good), but it is still the only bullet that is not closed with a period. For consistency with the other bullets in this doc-block – and with the style used across the other traits – please append a trailing “.”.

-* Skip processing with tags: `@behat-steps-skip:fileDownloadBeforeScenario` or
-* `@behat-steps-skip:fileDownloadAfterScenario`
+* Skip processing with tags: `@behat-steps-skip:fileDownloadBeforeScenario` or
+* `@behat-steps-skip:fileDownloadAfterScenario`.
src/MediaTrait.php (1)

20-21: 🧹 Nitpick (assertive)

Missing period – same nitpick as before

The “Skip processing with tag …” line is still missing its terminating period. This was pointed out in an earlier review; bringing it inline with the other list items keeps the documentation formatting consistent.

-* Skip processing with tag: `@behat-steps-skip:mediaAfterScenario`
+* Skip processing with tag: `@behat-steps-skip:mediaAfterScenario`.
docs.php (2)

210-212: 🧹 Nitpick (assertive)

Redundant array_values() resurrected – remove to silence PHPStan

array_map() already returns a numerically-indexed list, so the surrounding array_values() is a no-op and triggers the “arrayValues.list” warning again.
This optimisation was accepted in a previous commit — please keep the cleaned-up version.

-  $lines = array_values(
-    array_map(static fn($l): string => ltrim($l, " *\t"), explode(PHP_EOL, (string) $comment))
-  );
+  $lines = array_map(
+    static fn($l): string => ltrim($l, " *\t"),
+    explode(PHP_EOL, (string) $comment)
+  );

109-114: 💡 Verification agent

🧩 Analysis chain

*Filter for .php before treating a file as a trait

$traits_files[] = basename($file, '.php'); is executed for every file in src/, including README, .md, backups, etc.
If such a non-PHP artefact exists, the later “missing trait” safeguard will throw a false-positive exception and abort the docs build.

Add an extension check before adding to the list:

-      if (is_file($traits_path . DIRECTORY_SEPARATOR . $file)) {
+      if (
+        is_file($traits_path . DIRECTORY_SEPARATOR . $file)
+        && str_ends_with($file, '.php')
+      ) {
         $traits_files[] = basename($file, '.php');
       }

#!/bin/bash
set -e

# Locate docs.php
docs_file=$(fd docs.php -t f | head -n1)
echo "Found docs file at: ${docs_file}"

# Show where $files is populated
echo -e "\n--- Assignment to \$files ---"
grep -n "\$files\s*=" "${docs_file}" || echo "No direct assignment found."

# Show context around the foreach loop (lines ~80–140)
echo -e "\n--- Lines 80–140 of ${docs_file} ---"
sed -n '80,140p' "${docs_file}"

🏁 Script executed:

#!/bin/bash
set -e

# Locate docs.php
docs_file=$(fd docs.php -t f | head -n1)
echo "docs_file: $docs_file"

# Check how $files is populated
echo "--- grep for \$files assignment ---"
grep -n "\$files\s*=" "$docs_file" || true

# Check for scandir or glob usage
echo "--- grep for scandir( ---"
grep -n "scandir" "$docs_file" || true
echo "--- grep for glob( ---"
grep -n "glob" "$docs_file" || true

# Show lines around the foreach loop
echo "--- lines 1–80 ---"
sed -n '1,80p' "$docs_file"
echo "--- lines 80–140 ---"
sed -n '80,140p' "$docs_file"

Length of output: 4787


#!/bin/bash
set -e

# Locate composer.json
composer_file=$(fd composer.json -t f | head -n1)
echo "composer.json found at: $composer_file"

# Display PHP version requirement
echo -e "\n--- PHP version requirement ---"
grep -R '"php"' -n "$composer_file" || echo "No explicit PHP requirement found."

# Show the 'require' section for context
echo -e "\n--- 'require' section ---"
grep -R '"require"' -n "$composer_file" | head -n1 | cut -d: -f1 | xargs -I{} sed -n "{},+10p" "$composer_file"

Filter non-PHP files when collecting trait filenames

Should only include files ending in “.php” so artifacts like README.md or editor backups don’t get treated as missing traits. For example:

-    foreach ($files as $file) {
-      if (is_file($traits_path . DIRECTORY_SEPARATOR . $file)) {
-        $traits_files[] = basename($file, '.php');
-      }
-    }
+    foreach ($files as $file) {
+      if (
+        is_file($traits_path . DIRECTORY_SEPARATOR . $file)
+        && substr($file, -4) === '.php' // or use str_ends_with($file, '.php') on PHP 8+
+      ) {
+        $traits_files[] = basename($file, '.php');
+      }
+    }

This prevents non-PHP entries from being added and avoids spurious “missing trait” errors.

steps.md (10)

38-44: Unexpected inline HTML & double-space blockquotes in BigPipeTrait.
The blockquote uses <br/><br/> and two spaces after >, which triggers markdown-lint warnings (MD027, MD033). Replace with blank quoted lines and single spaces, for example:

- >  Bypass Drupal BigPipe when rendering pages.
- >  <br/><br/>
- >  Activated by adding `@big_pipe` tag to the scenario.
+ > Bypass Drupal BigPipe when rendering pages.
+ >
+ > Activated by adding `@big_pipe` tag to the scenario.
  > Skip processing with tags: `@behat-steps-skip:bigPipeBeforeScenario` …

50-56: Improve blockquote list spacing in BlockTrait.
Blockquotes containing lists should have blank quoted lines before and after the list to satisfy markdown-lint rules (MD007, MD032). For example:

- >  Manage Drupal blocks.
- >  - Create and configure blocks…
- >  - Place blocks in regions…
+ > Manage Drupal blocks.
+ >
+ > - Create and configure blocks…
+ > - Place blocks in regions…
+ >
+ > Skip processing with tag: `@behat-steps-skip:blockAfterScenario`

181-187: Improve blockquote list spacing in ContentBlockTrait.
Apply the same blank-line-around-lists adjustment here.


238-242: Improve blockquote list spacing in ContentTrait.
Apply the same blank-line-around-lists adjustment here.


321-324: Improve blockquote list spacing in CookieTrait.
Apply the same blank-line-around-lists adjustment here.


450-456: Unexpected inline HTML & double-space blockquotes in DateTrait.
Replace <br/><br/> and double spaces after > with blank quoted lines and single spaces.


723-729: Unexpected inline HTML & double-space blockquotes in EmailTrait.
Replace <br/><br/> and double spaces after > with blank quoted lines and single spaces.


1101-1104: Unexpected inline HTML & double-space blockquotes in FileDownloadTrait.
Replace <br/><br/> and double spaces after > with blank quoted lines and single spaces.


1836-1843: Unexpected inline HTML & double-space blockquotes in TestmodeTrait.
Replace <br/><br/> and double spaces after > with blank quoted lines and single spaces.


2067-2072: Unexpected inline HTML & double-space blockquotes in WatchdogTrait.
Replace <br/><br/> and double spaces after > with blank quoted lines and single spaces.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Lite

📥 Commits

Reviewing files that changed from the base of the PR and between 445c08b and 30108fd.

📒 Files selected for processing (31)
  • docs.php (6 hunks)
  • src/BigPipeTrait.php (1 hunks)
  • src/BlockTrait.php (1 hunks)
  • src/ContentBlockTrait.php (1 hunks)
  • src/ContentTrait.php (1 hunks)
  • src/CookieTrait.php (1 hunks)
  • src/DateTrait.php (1 hunks)
  • src/DraggableviewsTrait.php (1 hunks)
  • src/EckTrait.php (1 hunks)
  • src/ElementTrait.php (1 hunks)
  • src/EmailTrait.php (1 hunks)
  • src/FieldTrait.php (1 hunks)
  • src/FileDownloadTrait.php (1 hunks)
  • src/FileTrait.php (1 hunks)
  • src/KeyboardTrait.php (1 hunks)
  • src/LinkTrait.php (1 hunks)
  • src/MediaTrait.php (1 hunks)
  • src/MenuTrait.php (1 hunks)
  • src/MetatagTrait.php (1 hunks)
  • src/OverrideTrait.php (1 hunks)
  • src/ParagraphsTrait.php (2 hunks)
  • src/PathTrait.php (1 hunks)
  • src/ResponseTrait.php (1 hunks)
  • src/SearchApiTrait.php (1 hunks)
  • src/TaxonomyTrait.php (1 hunks)
  • src/TestmodeTrait.php (1 hunks)
  • src/UserTrait.php (1 hunks)
  • src/WaitTrait.php (1 hunks)
  • src/WatchdogTrait.php (1 hunks)
  • steps.md (23 hunks)
  • tests/phpunit/src/DocsTest.php (24 hunks)
🔇 Additional comments (26)
src/LinkTrait.php (1)

8-12: Docblock enhancements are appropriate
The updated description and bullet list clearly outline the trait’s verification capabilities for link elements. No further changes needed.

src/BigPipeTrait.php (1)

14-19: Docblock update is clear and informative
The description now explicitly covers activation with @big_pipe and skipping via tags, which enhances usability without altering logic. Looks good.

src/CookieTrait.php (1)

8-12: Docblock update is clear and concise
The refined description and bullet points accurately capture the trait’s cookie inspection capabilities and driver support. No changes required.

src/OverrideTrait.php (1)

10-20: LGTM: Clear and comprehensive documentation.

The updated docblock provides an excellent explanation of the trait's purpose, capabilities, and usage considerations. The specific behaviors being overridden are clearly outlined, and the integration guidance is well explained.

src/BlockTrait.php (1)

13-20: LGTM: Well-structured and informative docblock.

The documentation clearly explains the trait's purpose, capabilities, and cleanup mechanism. The inclusion of information about skipping processing with tags is particularly helpful for users.

src/FileTrait.php (1)

16-24: LGTM: Documentation structure is now consistent and clear.

The updated docblock provides comprehensive information about the trait's file management capabilities and cleanup options. The formatting of the "Skip processing with tags" section now properly uses a consistent style with the rest of the docblock.

src/ElementTrait.php (1)

8-12: LGTM! Clear and improved trait documentation.

The updated docblock provides a much clearer overview of the trait's functionality with well-structured bullet points that accurately describe its capabilities. This improvement aligns well with the documentation standards across other traits.

src/WatchdogTrait.php (1)

12-24: Well-structured and comprehensive documentation.

The updated docblock clearly explains the purpose of the trait and provides detailed information about its functionality. The documentation of special tags is particularly helpful for understanding how to control the trait's behavior in different scenarios.

src/ParagraphsTrait.php (2)

13-22: Well-structured and comprehensive class documentation!

The expanded docblock provides excellent clarity on what this trait does, from creating paragraphs to handling complex structures and automatic cleanup. This improved documentation will help developers understand the trait's capabilities and proper usage.


44-46: Good spacing improvement.

Adding this blank line improves code readability by visually separating the loop from the reset operation.

src/WaitTrait.php (1)

9-11: Improved docblock clarity.

The simplified trait description now uses the imperative form, making it consistent with other traits and clearly stating its purpose.

src/MetatagTrait.php (1)

9-13: More precise trait description.

The updated docblock improves clarity by:

  1. Using "Assert" instead of "Tests" for consistency with action-oriented descriptions
  2. Adding a specific capability bullet point that clearly explains what the trait does

This aligns well with the documentation style used across other traits.

src/KeyboardTrait.php (1)

11-16: Trait description looks good.

The updated docblock clearly explains the trait's purpose and capabilities. The bullet points are well-structured and provide comprehensive information about the functionality this trait offers.

src/DateTrait.php (1)

10-24: Good improvement to documentation that clearly explains the trait's purpose and functionality.

The documentation now provides a clear explanation of the trait's purpose along with detailed examples of how to use the relative date expressions. The examples are particularly helpful in illustrating the different formats supported.

src/ContentTrait.php (1)

13-17: Well-structured documentation that clearly outlines the trait's capabilities.

The expanded documentation now clearly describes the trait's purpose for managing Drupal content and specifies its capabilities in a bullet-point format, making it much easier to understand what functionality this trait provides at a glance.

src/FieldTrait.php (1)

13-17: Improved trait documentation with clear capability listing.

The revised documentation makes it much clearer what this trait does, with a good summary line followed by a structured list of capabilities. This helps developers quickly understand the purpose and features of this trait.

steps.md (1)

5-32: Table update approval – anchors and descriptions are correct.
I’ve verified that each trait in the table links ([TraitName](#traitname)) matches a corresponding ## TraitName heading and that descriptions are consistent.

tests/phpunit/src/DocsTest.php (9)

22-22: Good addition of coverage attribute for the new function.

The #[CoversFunction('parse_class_comment')] attribute correctly documents test coverage for the newly introduced function.


416-425: LGTM! Updated foreach loop to handle the new nested data structure.

The loop now correctly iterates over the restructured trait information data format.


435-486: Effective refactoring of test assertions.

The test assertions have been improved to validate specific content elements rather than exact string matches. This approach is more maintainable and less brittle when the rendered format changes slightly.


721-845: Well-structured test cases for enhanced documentation formatting.

The new test cases effectively verify the documentation system's ability to handle multi-paragraph descriptions, lists, and non-array properties.


853-856: Good defensive testing approach.

Sorting arrays before comparison ensures test stability by avoiding false failures due to arbitrary array ordering differences.


1182-1215: Well-handled edge cases for null and non-array steps.

Adding tests for null and non-array step handling improves test coverage for possible edge cases.


1281-1290: Comprehensive implementation of new function test.

The test method for parse_class_comment follows the established pattern with exception handling and proper result validation.


1292-1470: Thorough test coverage for class comment parsing scenarios.

The data provider includes an extensive variety of test cases covering valid and invalid formats, special characters, formatting edge cases, and error conditions. This provides excellent coverage for the new functionality.


1335-1369: Clear error message testing.

The error cases accurately test that appropriate exception messages are thrown for invalid comment scenarios, which is important for maintaining good developer experience.

Comment on lines +14 to 15
* Order items in the Drupal Draggable Views.
*/
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Expand docblock with detailed bullet list for clarity
Currently the trait-level comment is very brief. To match the style of other Behat traits, please enumerate its core steps, for example:

  • Remove existing ordering entries for the specified view and display.
  • Insert new records reflecting the provided item order.
  • Invalidate cache tags to ensure updated ordering is rendered.

Comment on lines +8 to 12
* Navigate and verify paths with URL validation.
*
* Path-related assertions.
*
* @package DrevOps\BehatSteps
* - Assert current page location with front page special handling.
* - Configure basic authentication for protected path access.
*/
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Documentation looks good, but paths need consistent treatment.

The updated docblock clearly describes the trait's purpose. However, looking at the actual implementation, there's a potential issue in the code: pathAssertNotCurrent() has a different handling of the front page path than pathAssertCurrent().

In pathAssertCurrent() (line 40), the empty path becomes <front>:

$current_path = $current_path === '' ? '<front>' : $current_path;

But in pathAssertNotCurrent() (line 72), only / becomes <front>:

$current_path = $current_path === '/' ? '<front>' : $current_path;

This inconsistency could lead to unexpected behavior.


🏁 Script executed:

#!/bin/bash
# Check for usages of the PathTrait methods to see how they're employed in tests
rg -A 2 -B 2 "pathAssertCurrent|pathAssertNotCurrent" --type php

Length of output: 574


Continuing verification to inspect the actual implementations:


🏁 Script executed:

#!/bin/bash
# Show the implementation of both methods in src/PathTrait.php
rg -n "public function pathAssertCurrent" -A10 -B2 src/PathTrait.php
rg -n "public function pathAssertNotCurrent" -A10 -B2 src/PathTrait.php

Length of output: 1067


Continuing verification to inspect the exact normalization lines:


🏁 Script executed:

#!/bin/bash
rg -n "<front>" -A2 -B2 src/PathTrait.php

Length of output: 885


Normalize front-page path handling in PathTrait

The two assertions treat <front> differently—pathAssertCurrent() only normalizes an empty string, whereas pathAssertNotCurrent() normalizes "/". As a result, when the session URL parses to "/", pathAssertCurrent() will not recognize it as the front page.

Locations to fix:

  • src/PathTrait.php around line 40 (in pathAssertCurrent())
  • (Optional) You may also simplify pathAssertNotCurrent() around line 72 to match the same logic

Proposed change in pathAssertCurrent():

--- a/src/PathTrait.php
+++ a/src/PathTrait.php
@@ -38,7 +38,9 @@
-    $current_path = $current_path === '' ? '<front>' : $current_path;
+    // Treat both "" and "/" as the front page
+    $current_path = in_array($current_path, ['', '/'], true)
+      ? '<front>' : $current_path;

This ensures both methods consistently map the front page to <front>.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
* Navigate and verify paths with URL validation.
*
* Path-related assertions.
*
* @package DrevOps\BehatSteps
* - Assert current page location with front page special handling.
* - Configure basic authentication for protected path access.
*/
// Treat both "" and "/" as the front page
$current_path = in_array($current_path, ['', '/'], true)
? '<front>' : $current_path;

Comment on lines +151 to +154
$parsed_comment = parse_method_comment((string) $method->getDocComment());
if ($parsed_comment) {
// @phpstan-ignore-next-line
$class_info['methods'][] = $parsed_comment + ['name' => $method->getName()];
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

class_name missing again – breaks consumers that rely on it

Earlier feedback added class_name to every method entry; however the line was reverted:

$class_info['methods'][] = $parsed_comment + ['name' => $method->getName()];

Down-stream code (e.g. custom tooling or future consumers) may expect this field just like the unit-test fixtures do. Re-introducing it keeps the structure self-contained and future-proof.

-        $class_info['methods'][] = $parsed_comment + ['name' => $method->getName()];
+        $class_info['methods'][] = $parsed_comment + [
+          'name'       => $method->getName(),
+          'class_name' => $trait_name,
+        ];

Comment on lines +239 to +241
if (substr_count($full_description, '`') % 2 !== 0) {
throw new \Exception(sprintf('Class inline code block is not closed for %s', $trait_name));
}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

⚠️ Potential issue

Inline-code fence heuristic will falsely flag ``` blocks

substr_count($full_description, '') % 2 !== 0` counts every back-tick, so a single fenced block

```php
code
contains **three** back-ticks and fails the “balanced” check even though it’s perfectly valid.

Consider either:

1. Strip ```…``` fences before counting single-tick inlines, or  
2. Replace with a regex that matches *inline* back-ticks only.




I can provide a tested regex replacement if you’d like.

<!-- This is an auto-generated comment by CodeRabbit -->

Comment on lines +464 to +467
if (isset($method['example']) && $method['example'] === 123) {
// Skip this check.
}
else {
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Clarify the purpose of skipping this check.

The comment "Skip this check" doesn't explain why this specific test case needs special handling.

-              // For this specific test case, we'll skip the example content check.
-              if (isset($method['example']) && $method['example'] === 123) {
-                // Skip this check.
-              }
+              // Skip example content verification for numeric examples since they're converted to strings elsewhere
+              if (isset($method['example']) && $method['example'] === 123) {
+                // Skip numeric example content check since we're testing type handling, not exact content
+              }

Committable suggestion skipped: line range outside the PR's diff.

@AlexSkrypnyk AlexSkrypnyk merged commit c29f390 into 3.x May 5, 2025
4 of 5 checks passed
@AlexSkrypnyk AlexSkrypnyk deleted the feature/update-trait-docs branch May 5, 2025 00:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant
0