[#760] Expanded fixture paths for file and image fields in subdirectories.

[AlexSkrypnyk]

Closes #760

Summary

Fixture file paths for file and image fields on entity stubs stopped expanding as soon as the value contained a path separator, so a value like images/500x200.png was passed straight through to drupal-driver and failed with file_get_contents(images/500x200.png): Failed to open stream instead of being rewritten to an absolute path under the Mink files_path. Only bare filenames such as 500x200.png worked. HelperTrait::helperExpandFixtureFiles() and helperExpandCompoundCellFixtures() now resolve the value relative to the fixtures directory through a new helperResolveFixtureFile() method instead of rejecting anything containing a separator. ContentTrait is updated to describe the same behaviour for node file/image fields.

Changes

• src/Drupal/HelperTrait.php: replaced the separator-rejection check in helperExpandFixtureFiles() and helperExpandCompoundCellFixtures() with a call to the new helperResolveFixtureFile(), which treats the value as relative to the fixtures directory, leaves stream URIs (public://...) and absolute paths for drupal-driver to resolve, and confirms the resolved realpath stays inside the fixtures directory so a ../ value cannot escape it.
• src/Drupal/ContentTrait.php: updated the docblock on the node file/image expansion method to describe subdirectory paths alongside bare filenames.
• tests/phpunit/src/Drupal/HelperTraitTest.php: extended createFixtureFiles() to create parent directories as needed, and added cases covering a subdirectory fixture, a nested multi-level fixture, a multi-value list of subdirectory fixtures, a missing subdirectory fixture, a stream URI, an absolute path, and a ../ traversal attempt.
• tests/behat/features/drupal_content.feature and tests/behat/features/drupal_media.feature: added scenarios that create a node and a media entity with a file/image field value pointing at a fixture in a subdirectory.

Before / After

Before:
  field_file: "images/500x200.png"
        │
        ▼
  contains "/" ──► rejected, value passed through unchanged
        │
        ▼
  drupal-driver: file_get_contents(images/500x200.png)
        │
        ▼
  Failed to open stream (fixture never resolved)

After:
  field_file: "images/500x200.png"
        │
        ▼
  helperResolveFixtureFile(value, fixture_path)
        │
        ├─ contains "://"            ──► NULL (left for drupal-driver)
        ├─ starts with "/", "\", "C:\" ──► NULL (left for drupal-driver)
        ├─ not a file under fixture_path ──► NULL (left unchanged)
        ├─ realpath escapes fixture_path ──► NULL (left unchanged)
        └─ otherwise                  ──► absolute path under files_path
        │
        ▼
  drupal-driver reads the resolved absolute path and uploads it

Summary

• Restore nested fixture path support for file and image fields.
• Resolve valid relative paths under Mink’s fixtures directory.
• Preserve stream URIs and absolute paths.
• Reject missing files and paths that escape the fixtures directory.
• Apply the resolver to regular field values and compound target_id values.
• Update documentation, PHPUnit tests, and Behat scenarios for nested, multiple, missing, absolute, stream, and traversal paths.

Critical

• Step-definition compliance could not be assessed because CONTRIBUTING.md content was not available.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d51d268e-b366-44b8-936b-4e55f0904134

📥 Commits

Reviewing files that changed from the base of the PR and between c400050 and 5204606.

📒 Files selected for processing (5)

• src/Drupal/ContentTrait.php
• src/Drupal/HelperTrait.php
• tests/behat/features/drupal_content.feature
• tests/behat/features/drupal_media.feature
• tests/phpunit/src/Drupal/HelperTraitTest.php

Included review availability: 8 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

---

Walkthrough

Nested fixture paths now resolve to absolute paths under Mink’s fixture directory. The shared resolver validates file existence and directory boundaries. Field values, compound target_id cells, PHPUnit tests, and Behat scenarios cover the new behavior.

Changes

Drupal fixture path resolution

Layer / File(s)	Summary
Fixture resolver contract src/Drupal/HelperTrait.php, src/Drupal/ContentTrait.php	Documentation describes nested fixture paths. The resolver rejects stream URIs, absolute paths, missing files, and paths outside the fixture directory.
Field value expansion src/Drupal/HelperTrait.php	Parsed field values and compound target_id cells use the shared resolver while preserving managed-file handling.
Fixture creation and validation tests/phpunit/src/Drupal/HelperTraitTest.php, tests/behat/features/drupal_content.feature, tests/behat/features/drupal_media.feature	Tests create nested fixtures and verify valid, missing, absolute, stream-wrapper, and traversal paths. Behat scenarios cover content and media uploads.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 52046

The change enables file and image fixtures in nested directories while preserving handling for stream URIs, absolute paths, missing files, and traversal attempts. No actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant API scenario
  participant HelperTrait
  participant helperResolveFixtureFile
  participant FileHandler
  API scenario->>HelperTrait: Provide nested fixture path
  HelperTrait->>helperResolveFixtureFile: Validate and resolve path
  helperResolveFixtureFile-->>HelperTrait: Return absolute fixture path
  HelperTrait->>FileHandler: Pass resolved path for upload
  FileHandler-->>API scenario: Create field value

Loading

Poem

A rabbit files paths in a directory deep
Nested documents no longer sleep
The helper checks each trail
Safe paths pass without fail
PDFs now hop where fixtures keep

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 3 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: expanding fixture paths for file and image fields in subdirectories.
Linked Issues check	✅ Passed	The changes satisfy issue #760 by resolving nested fixture paths relative to the configured fixtures directory while preserving support for managed files, stream URIs, absolute paths, missing files, a…
Out of Scope Changes check	✅ Passed	The documentation, implementation, unit tests, and Behat scenarios are directly related to nested fixture path resolution. No unrelated changes are present.

Full details: Linked Issues check

Explanation

The changes satisfy issue #760 by resolving nested fixture paths relative to the configured fixtures directory while preserving support for managed files, stream URIs, absolute paths, missing files, and traversal protection. Tests cover the required cases.

Full details: Docstring Coverage

Explanation

Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 3 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/fixture-subdirs

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 95.45455% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.53%. Comparing base (c400050) to head (5204606).

Files with missing lines	Patch %	Lines
src/Drupal/HelperTrait.php	95.45%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #764      +/-   ##
==========================================
+ Coverage   97.47%   97.53%   +0.06%     
==========================================
  Files          52       52              
  Lines        4548     4552       +4     
==========================================
+ Hits         4433     4440       +7     
+ Misses        115      112       -3     

☔ View full report in Codecov by Harness.
📢 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.