From e6239f99cd4fdbbac7ab128aba0b71b7168619ae Mon Sep 17 00:00:00 2001 From: Julien Nahum Date: Sat, 15 Mar 2025 10:21:31 +0800 Subject: [PATCH] Enhance Back-end and Front-end Documentation - Update back-end rules to include support for nested PHP files and added debugging guidelines using ray(). - Expand front-end rules to specify the use of form components from client/components/forms and wrapping them in @VForm.vue. These changes improve clarity and best practices for both back-end and front-end development, ensuring consistency and better debugging practices across the codebase. --- .cursor/rules/back-end-testing.mdc | 121 +++++++++++++++++++++++++++++ .cursor/rules/back-end.mdc | 7 +- .cursor/rules/front-end.mdc | 4 + 3 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 .cursor/rules/back-end-testing.mdc diff --git a/.cursor/rules/back-end-testing.mdc b/.cursor/rules/back-end-testing.mdc new file mode 100644 index 00000000..76a3c38f --- /dev/null +++ b/.cursor/rules/back-end-testing.mdc @@ -0,0 +1,121 @@ +--- +description: Laravel Back-end Tests +globs: api/tests/**/*.php +--- + +You are an expert in Laravel testing, particularly with Pest PHP for the Laravel back-end. + +Key Principles +- Write concise, isolated tests that verify specific functionality. +- Follow the Arrange-Act-Assert pattern for test structure. +- Use descriptive test names that explain what is being tested. +- Prefer Pest PHP's expressive syntax over traditional PHPUnit syntax. +- Use mocking and test doubles appropriately to isolate components. +- Organize tests by the component they are testing. + +Test Structure +- `tests/Feature/`: Contains feature tests that test the application as a whole. +- `tests/Unit/`: Contains unit tests that test individual components in isolation. + - `Unit/Rules/`: Tests for validation rules. + - `Unit/Service/`: Tests for service classes. + - `Unit/Services/`: Tests for service classes (alternative structure). +- `tests/Helpers/`: Contains helper classes used across tests. +- `tests/Browser/`: Contains browser tests using Laravel Dusk. + +Test Configuration +- Use `tests/Pest.php` for Pest PHP configuration. +- Use `tests/TestCase.php` as the base test case class. +- Use `tests/TestHelpers.php` for common helper methods. + +Unit Testing Best Practices +1. **Test in Isolation**: Mock dependencies to ensure true unit testing. +2. **Single Responsibility**: Each test should verify one specific behavior. +3. **Descriptive Names**: Use descriptive test names that explain what is being tested. +4. **Arrange-Act-Assert**: Structure tests with clear arrangement, action, and assertion phases. +5. **Test Edge Cases**: Include tests for edge cases and error conditions. +6. **Use describe()**: Group related tests using describe() blocks. +7. **Use beforeEach()**: Set up common test state using beforeEach() hooks. +8. **Avoid Test Dependencies**: Tests should not depend on the state from other tests. +9. **Test Public API**: Focus on testing the public API of classes, not implementation details. +10. **Consistent Patterns**: Follow consistent patterns for similar types of tests. + +Writing Unit Tests +- Use Pest PHP's expressive syntax: + ```php + it('can parse filenames', function () { + $fileName = 'example_85e16d7b-58ed-43bc-8dce-7d3ff7d69f41.png'; + $parsedFilename = StorageFileNameParser::parse($fileName); + expect($parsedFilename->fileName)->toBe('example'); + }); + ``` + +- Group related tests with describe(): + ```php + describe('StorageFile validation', function () { + it('accepts valid URLs without validation', function () { + $validator = new StorageFile(); + expect($validator->passes('file', 'https://example.com/file.pdf'))->toBeTrue(); + }); + + it('rejects files with invalid UUID format', function () { + $validator = new StorageFile(); + expect($validator->passes('file', 'invalid-uuid.jpg'))->toBeFalse(); + }); + }); + ``` + +- Use beforeEach() for common setup: + ```php + beforeEach(function () { + Storage::fake('local'); + }); + ``` + +- Mock dependencies: + ```php + it('rejects non-existent files', function () { + $uuid = Str::uuid(); + $fileName = 'file-name_' . $uuid . '.jpg'; + + Storage::shouldReceive('exists') + ->with('tmp/' . $uuid) + ->andReturn(false); + + $validator = new StorageFile(); + expect($validator->passes('file', $fileName))->toBeFalse(); + }); + ``` + +- Test edge cases: + ```php + it('can clean non-utf characters', function () { + $fileName = 'Образец_для_заполнения_85e16d7b-58ed-43bc-8dce-7d3ff7d69f41.png'; + $parsedFilename = StorageFileNameParser::parse($fileName); + expect($parsedFilename->getMovedFileName())->toBe('___85e16d7b-58ed-43bc-8dce-7d3ff7d69f41.png'); + }); + ``` + +Testing Validation Rules +- Create instances of the rule class. +- Test both valid and invalid inputs. +- Verify error messages for invalid inputs. +- Test edge cases and boundary conditions. + +Testing Service Classes +- Mock dependencies using Mockery. +- Test each public method in isolation. +- Verify correct behavior for both success and failure cases. +- Test edge cases and error handling. + +Running Tests +- Run all tests: `php artisan test` +- Run unit tests only: `php artisan test --testsuite=Unit` +- Run a specific test file: `php artisan test --filter=StorageFileTest` +- Run tests with coverage: `php artisan test --coverage` + +Debugging Tests +- Use ray() for debugging test execution. +- Use dd() or dump() for quick inspection of variables. +- Check for race conditions in asynchronous tests. +- Verify that the database is being properly reset between tests. +- Ensure that tests are not dependent on each other. \ No newline at end of file diff --git a/.cursor/rules/back-end.mdc b/.cursor/rules/back-end.mdc index cc9c69d8..de99269b 100644 --- a/.cursor/rules/back-end.mdc +++ b/.cursor/rules/back-end.mdc @@ -1,6 +1,6 @@ --- description: Laravel Back-end -globs: api/**.php +globs: api/**/*.php --- You are an expert in Laravel, PHP, and related web development technologies. @@ -43,6 +43,11 @@ Laravel Best Practices - Use Laravel's built-in pagination features. - Implement proper error logging and monitoring. +Debugging +- Always use ray() for debugging +- Never add any import for ray like use Illuminate\Support\Facades\Ray, just use ray() function direcly +- Use ray methods to add more context and improve display when needed @https://myray.app/docs/php/vanilla-php/reference + Key Conventions 1. Follow Laravel's MVC architecture. 2. Use Laravel's routing system for defining application endpoints. diff --git a/.cursor/rules/front-end.mdc b/.cursor/rules/front-end.mdc index d4076f5b..b0505f66 100644 --- a/.cursor/rules/front-end.mdc +++ b/.cursor/rules/front-end.mdc @@ -26,6 +26,10 @@ UI and Styling - Implement responsive design with Tailwind CSS; use a mobile-first approach. - Build UI components using atomic design principles, organizing them from smallest to largest (e.g., atoms, molecules, organisms, pages). +Forms +- For forms inputs, use the components in client/components/forms such as etc. +- Wrap then in @VForm.vue + Performance Optimization - Leverage VueUse functions where applicable to enhance reactivity and performance. - Wrap asynchronous components in Suspense with a fallback UI made with components.