From 8a1263bd5077eca825a159463e71c65586fbf7f5 Mon Sep 17 00:00:00 2001
From: Nicola Zangrandi <wasp@wasp.ovh>
Date: Fri, 21 Feb 2025 13:28:42 +0100
Subject: [PATCH] docs(rules): update frontend testing and Bulma usage
 standards

- Add reliable test execution patterns
- Add dark mode implementation details
- Add specific component patterns
- Update examples with real-world usage
---
 .cursor/rules/bulma-usage.mdc      | 153 ++++++++++++++++-------------
 .cursor/rules/frontend-testing.mdc |  56 ++++++++---
 2 files changed, 126 insertions(+), 83 deletions(-)

diff --git a/.cursor/rules/bulma-usage.mdc b/.cursor/rules/bulma-usage.mdc
index 6547834..ea8d92e 100644
--- a/.cursor/rules/bulma-usage.mdc
+++ b/.cursor/rules/bulma-usage.mdc
@@ -18,90 +18,101 @@ When styling components:
    - Keep modifier classes consistent with Bulma's patterns
    - Use semantic Bulma classes (e.g., 'button is-primary' not custom colors)
 
-3. Custom Styles:
-   - Only add custom CSS when Bulma doesn't provide the functionality
-   - Document why custom CSS is needed
-   - Use Bulma's CSS variables for theming
-   - Keep custom styles minimal and focused
+3. Dark Mode Implementation:
+   - Define CSS variables in app.html for global theme
+   - Use --bulma-* prefix for all theme variables
+   - Override component-specific variables as needed
+   - Test all components in both light/dark modes
+   - Common variables to define:
+     ```css
+     body.dark-mode {
+       --bulma-scheme-main: #1a1a1a;
+       --bulma-scheme-main-bis: #242424;
+       --bulma-scheme-main-ter: #2f2f2f;
+       --bulma-text: #e6e6e6;
+       --bulma-text-strong: #ffffff;
+       --bulma-border: #4a4a4a;
+     }
+     ```
 
-4. Dark Mode:
-   - Use Bulma's CSS variables for theming
-   - Override colors using CSS variables, not direct colors
-   - Maintain consistent contrast ratios
-   - Test dark mode for all components
+4. Navigation Patterns:
+   - Mobile: Use fixed bottom navbar
+   - Desktop: Use fixed left sidebar
+   - Handle responsive transitions cleanly
+   - Use consistent icon + label patterns
+   - Maintain active state indicators
 
-5. Responsive Design:
-   - Use Bulma's responsive classes (is-*-mobile, is-*-tablet, etc.)
+5. Card Patterns:
+   - Use standard card structure:
+     ```html
+     <div class="card">
+       <div class="card-content">
+         <p class="title is-4">Title</p>
+         <p class="subtitle is-6">Subtitle</p>
+         <div class="content">Content</div>
+       </div>
+       <footer class="card-footer">
+         <a class="card-footer-item">Action</a>
+       </footer>
+     </div>
+     ```
+   - Keep actions in card-footer
+   - Use consistent spacing
+   - Handle long content gracefully
+
+6. Form Patterns:
+   - Use standard field structure:
+     ```html
+     <div class="field">
+       <label class="label">Label</label>
+       <div class="control">
+         <input class="input" />
+       </div>
+     </div>
+     ```
+   - Group related fields with field-group
+   - Use appropriate input types
+   - Add helper text when needed
+
+7. Responsive Design:
+   - Use Bulma's responsive classes
    - Test all breakpoints
-   - Maintain consistent spacing across screen sizes
+   - Maintain consistent spacing
    - Use proper container classes
-
-6. Common Patterns:
-   - Forms: field > label + control > input
-   - Buttons: button + is-* modifiers
-   - Cards: card > card-header + card-content + card-footer
-   - Navigation: navbar with proper structure
-   - Grid: columns > column with proper sizes
-
-7. Performance:
-   - Don't duplicate Bulma styles
-   - Minimize custom CSS
-   - Use Bulma's minified version
-   - Remove unused Bulma features if size is a concern
+   - Handle mobile-specific patterns:
+     - Touch-friendly tap targets
+     - Simplified navigation
+     - Adjusted font sizes
+     - Full-width buttons
 
 metadata:
   priority: high
-  version: 1.0
+  version: 1.1
 </rule>
 
 examples:
   - input: |
-      # Bad: Custom styles for spacing
-      <style>
-        .my-component {
-          margin-bottom: 20px;
-          padding: 15px;
-        }
-      </style>
+      # Bad: Custom dark mode colors
+      .dark-mode .button {
+        background: #333;
+        color: white;
+      }
     output: |
-      <!-- Good: Bulma utilities -->
-      <div class="mb-5 p-4">...</div>
+      # Good: Theme variables
+      body.dark-mode {
+        --bulma-button-background-color: #363636;
+        --bulma-button-color: #e6e6e6;
+      }
 
   - input: |
-      # Bad: Custom color styles
-      <style>
-        .custom-button {
-          background: #3273dc;
-          color: white;
-        }
-      </style>
+      # Bad: Inconsistent navigation
+      <div class="nav-mobile">...</div>
+      <div class="sidebar">...</div>
     output: |
-      <!-- Good: Bulma color classes -->
-      <button class="button is-primary">...</button>
-
-  - input: |
-      # Bad: Custom responsive styles
-      <style>
-        @media (max-width: 768px) {
-          .hide-mobile { display: none; }
-        }
-      </style>
-    output: |
-      <!-- Good: Bulma responsive classes -->
-      <div class="is-hidden-mobile">...</div>
-
-  - input: |
-      # Bad: Inconsistent form structure
-      <div>
-        <label>Name</label>
-        <input type="text">
-      </div>
-    output: |
-      <!-- Good: Bulma form structure -->
-      <div class="field">
-        <label class="label">Name</label>
-        <div class="control">
-          <input class="input" type="text">
-        </div>
-      </div>
+      # Good: Responsive navigation
+      {#if isMobile}
+        <nav class="navbar is-fixed-bottom">...</nav>
+      {:else}
+        <nav class="menu is-fixed-left">...</nav>
+      {/if}
 </rewritten_file> 
\ No newline at end of file
diff --git a/.cursor/rules/frontend-testing.mdc b/.cursor/rules/frontend-testing.mdc
index db7b86e..f33eb2d 100644
--- a/.cursor/rules/frontend-testing.mdc
+++ b/.cursor/rules/frontend-testing.mdc
@@ -14,10 +14,10 @@ When working on frontend features:
 
 2. Test Structure:
    - Use descriptive test names
+   - Reset database state before each test
    - Group related tests in describe blocks
-   - Use beforeEach for common setup
-   - Clean up test data after each test
    - Keep tests focused and atomic
+   - Add explicit waits and checks at key points
 
 3. Testing Best Practices:
    - Test user interactions, not implementation
@@ -26,7 +26,16 @@ When working on frontend features:
    - Test across multiple browsers
    - Verify visual and functional aspects
 
-4. Required Test Cases:
+4. Reliable Test Execution:
+   - Always reset database state with `/api/test/reset`
+   - Wait for redirects with URL checks
+   - Wait for content with `.waitForSelector()`
+   - Check element visibility before interaction
+   - Use specific selectors (id, role, exact text)
+   - Add explicit waits after state changes
+   - Store URLs after navigation for reliable returns
+
+5. Required Test Cases:
    - Navigation flows
    - Form submissions
    - Error handling
@@ -34,25 +43,48 @@ When working on frontend features:
    - Responsive behavior
    - Cross-browser compatibility
 
-5. Running Tests:
+6. Database Considerations:
+   - Use single worker mode due to shared database
+   - Reset database state before each test
+   - Avoid parallel test execution
+   - Consider test isolation needs
+
+7. Running Tests:
    - Run tests before committing: `bun test`
    - Debug tests with UI: `bun test:ui`
    - Debug specific test: `bun test:debug`
    - Install browsers: `bun test:install`
 
-6. CI Integration:
-   - Tests must pass in CI
-   - Screenshots on failure
-   - HTML test reports
-   - Retry failed tests
-   - Parallel execution where possible
-
 metadata:
   priority: high
-  version: 1.0
+  version: 1.1
 </rule>
 
 examples:
+  - input: |
+      # Bad: Unreliable waiting
+      await page.click('button');
+      await page.locator('h1').textContent();
+    output: |
+      # Good: Explicit waits and checks
+      await page.click('button');
+      await expect(page).toHaveURL(/\/expected-path/);
+      await page.waitForSelector('h1');
+      await expect(page.locator('h1')).toBeVisible();
+
+  - input: |
+      # Bad: No state reset
+      test('creates item', async ({ page }) => {
+        await page.goto('/items/new');
+      });
+    output: |
+      # Good: Reset state first
+      test('creates item', async ({ page }) => {
+        await page.goto('/');
+        await page.request.post('/api/test/reset');
+        await page.goto('/items/new');
+      });
+
   - input: |
       # Bad: No tests for new feature
       git commit -m "feat: add note search"