Module Filesystem Laravel Package

Getting Started

Begin by installing via Composer: composer require --dev codeception/module-filesystem. Then enable it in your acceptance.suite.yml, functional.suite.yml, or unit.suite.yml under modules:. The module provides assertions and helpers to verify filesystem state—e.g., checking if a file exists, directory has specific contents, or file contents match expected patterns. Your first use case is likely asserting file output after a command or fixture generation: I->seeFileFound('storage/app/logs/app.log') or I->seeFileContentsEqual('Expected content', 'config/test.yaml').

Implementation Patterns

Use this module for deterministic filesystem assertions in tests—especially in functional/acceptance suites. Common patterns include:

• Cleanup & Reset: Call $I->cleanDir('storage/app') in tearDown() or _before() to ensure isolated test runs.
• Fixture Verification: After a CLI command that writes files (e.g., make:report), assert contents with $I->seeFileContains('report.txt', 'Q3 Results').
• Directory Tree Checks: Use $I->seeFileStructureEquals(['config/', 'config/app.php', 'storage/']) to validate scaffolded structures.
• Symlink/Permission Tests: Verify symlinks ($I->seeFileIsSymlink('link.txt')) or permissions ($I->seeFileHasPermissions('public/file.txt', '0644')).
  Integrate with other modules (e.g., Symfony, Laravel) by placing it after them in suite config to ensure filesystem state is observable post-request.

Gotchas and Tips

• Absolute Paths: Prefer absolute paths in assertions to avoid ambiguity—relative paths resolve relative to the suite's support directory, not the project root.
• File Existence vs Content: Distinguish between $I->seeFileFound() (existence only) and $I->seeFileContentsEqual() (exact content match). For partial matches, use $I->seeFileContains().
• Case Sensitivity: File existence checks are case-sensitive on Linux but not macOS/Windows—use consistent naming in cross-platform tests.
• Symlinks: seeFileIsSymlink() returns false for broken symlinks; pair with seeFileFound() to confirm target.
• Fixture Management: Avoid writing large files in tests; use seeFileContentsMatch('/pattern/i') instead of full content comparison for resilience.
• Extension: Override Codeception\Module\Filesystem::getDirectory() in a custom module to inject dynamic base paths for multi-environment setups.
• Empty Directory Quirk: cleanDir() deletes contents but keeps the directory—use deleteDir() to remove entirely.