@nextsparkjs/theme-default 0.1.0-beta.1 → 0.1.0-beta.101

package/tests/cypress/e2e/_utils/selectors/billing.bdd.md

@@ -0,0 +1,276 @@
+---
+feature: Billing UI Selectors Validation
+priority: high
+tags: [selectors, billing, ui-validation]
+grepTags: [ui-selectors, billing, SEL_BILL_001, SEL_BILL_002, SEL_BILL_003, SEL_BILL_004, SEL_BILL_005, SEL_BILL_006, SEL_BILL_DOC]
+coverage: 7
+---
+
+# Billing UI Selectors Validation
+
+> Validates that billing component selectors exist in the DOM. This is a lightweight test that ONLY checks selector presence, not functionality. Most tests are skipped due to permission requirements (OWNER role only) or specific state requirements (paid subscription, downgrade flow).
+
+**IMPORTANT:** Billing page requires `settings.billing` permission which only OWNER role has. See also: `settings-billing.cy.ts` for additional billing page selectors.
+
+## @test SEL_BILL_001: Billing Page Structure
+
+### Metadata
+- **Priority:** High
+- **Type:** Selector Validation
+- **Tags:** billing, page, structure
+- **Grep:** `@ui-selectors` `@SEL_BILL_001`
+- **Status:** Skipped - requires OWNER permission
+
+```gherkin:en
+Scenario: Billing page has complete structure
+
+Given I am logged in as OWNER
+And I navigate to the billing settings page
+Then I should find the billing main container
+And I should find the billing header
+And I should find the upgrade plan button
+And I should find the add payment button
+```
+
+```gherkin:es
+Scenario: Pagina de billing tiene estructura completa
+
+Given estoy logueado como OWNER
+And navego a la pagina de configuracion de billing
+Then deberia encontrar el contenedor principal de billing
+And deberia encontrar el header de billing
+And deberia encontrar el boton de upgrade plan
+And deberia encontrar el boton de agregar pago
+```
+
+### Expected Results
+- `billing-main` selector exists
+- `billing-header` selector exists
+- `billing-upgrade-plan` selector exists
+- `billing-add-payment` selector exists
+
+### Notes
+All tests skipped because billing page requires `settings.billing` permission which only OWNER role has.
+
+---
+
+## @test SEL_BILL_002: Invoices Section
+
+### Metadata
+- **Priority:** High
+- **Type:** Selector Validation
+- **Tags:** billing, invoices, table
+- **Grep:** `@ui-selectors` `@SEL_BILL_002`
+- **Status:** Skipped - requires OWNER permission
+
+```gherkin:en
+Scenario: Billing page has invoices section
+
+Given I am logged in as OWNER
+And I navigate to the billing settings page
+Then I should find the invoices table
+And I should find invoice rows (when invoices exist)
+And I should find load more button (when many invoices)
+And I should find invoice status badges
+```
+
+```gherkin:es
+Scenario: Pagina de billing tiene seccion de facturas
+
+Given estoy logueado como OWNER
+And navego a la pagina de configuracion de billing
+Then deberia encontrar la tabla de facturas
+And deberia encontrar filas de facturas (cuando existen)
+And deberia encontrar boton cargar mas (cuando hay muchas)
+And deberia encontrar badges de estado de factura
+```
+
+### Expected Results
+- `invoices-table` selector exists
+- `invoices-row` selector exists (when invoices present)
+- `invoices-load-more` selector exists (when more invoices available)
+- `invoice-status-badge` selector exists (when invoices present)
+
+---
+
+## @test SEL_BILL_003: Usage Display
+
+### Metadata
+- **Priority:** Medium
+- **Type:** Selector Validation
+- **Tags:** billing, usage, limits
+- **Grep:** `@ui-selectors` `@SEL_BILL_003`
+- **Status:** Skipped - requires OWNER permission
+
+```gherkin:en
+Scenario: Billing page displays usage information
+
+Given I am logged in as OWNER
+And I navigate to the billing settings page
+Then I should see usage numbers in format "X / Y"
+And I should find the usage dashboard component
+```
+
+```gherkin:es
+Scenario: Pagina de billing muestra informacion de uso
+
+Given estoy logueado como OWNER
+And navego a la pagina de configuracion de billing
+Then deberia ver numeros de uso en formato "X / Y"
+And deberia encontrar el componente usage dashboard
+```
+
+### Expected Results
+- Usage numbers displayed in format `N / M`
+- `usage-dashboard` selector exists
+
+---
+
+## @test SEL_BILL_004: ManageBillingButton
+
+### Metadata
+- **Priority:** Low
+- **Type:** Selector Validation
+- **Tags:** billing, manage, stripe
+- **Grep:** `@ui-selectors` `@SEL_BILL_004`
+- **Status:** Skipped - requires paid Stripe subscription
+
+```gherkin:en
+Scenario: Billing page has manage billing button for paid users
+
+Given I am logged in as a user with paid subscription
+And the subscription has an external Stripe customer ID
+And I navigate to the billing settings page
+Then I should find the manage billing button
+```
+
+```gherkin:es
+Scenario: Pagina de billing tiene boton de gestionar billing para usuarios de pago
+
+Given estoy logueado como usuario con suscripcion de pago
+And la suscripcion tiene un ID de cliente externo de Stripe
+And navego a la pagina de configuracion de billing
+Then deberia encontrar el boton de gestionar billing
+```
+
+### Expected Results
+- `manage-billing-button` selector exists
+
+### Notes
+ManageBillingButton only renders when `subscription.externalCustomerId` exists (Stripe customer).
+
+---
+
+## @test SEL_BILL_005: SubscriptionStatus
+
+### Metadata
+- **Priority:** Low
+- **Type:** Selector Validation
+- **Tags:** billing, subscription, status
+- **Grep:** `@ui-selectors` `@SEL_BILL_005`
+- **Status:** Skipped - requires active subscription
+
+```gherkin:en
+Scenario: Billing page shows subscription status for subscribers
+
+Given I am logged in as a user with active subscription
+And I navigate to the billing settings page
+Then I should find the subscription status container
+And I should find the subscription plan name
+And I should find the subscription status badge
+```
+
+```gherkin:es
+Scenario: Pagina de billing muestra estado de suscripcion para suscriptores
+
+Given estoy logueado como usuario con suscripcion activa
+And navego a la pagina de configuracion de billing
+Then deberia encontrar el contenedor de estado de suscripcion
+And deberia encontrar el nombre del plan de suscripcion
+And deberia encontrar el badge de estado de suscripcion
+```
+
+### Expected Results
+- `subscription-status` selector exists
+- `subscription-status-plan` selector exists
+- `subscription-status-badge` selector exists
+
+---
+
+## @test SEL_BILL_006: DowngradeWarning
+
+### Metadata
+- **Priority:** Low
+- **Type:** Selector Validation
+- **Tags:** billing, downgrade, warning
+- **Grep:** `@ui-selectors` `@SEL_BILL_006`
+- **Status:** Skipped - requires downgrade flow with over-limit resources
+
+```gherkin:en
+Scenario: Downgrade warning appears when user has over-limit resources
+
+Given I am attempting to downgrade my subscription
+And I have resources that exceed the new plan limits
+Then I should see the downgrade warning alert
+And I should see the warning title
+And I should see the warning description
+And I should see the list of over-limit resources
+And I should see the confirm downgrade button
+And I should see the cancel button
+```
+
+```gherkin:es
+Scenario: Advertencia de downgrade aparece cuando usuario tiene recursos sobre el limite
+
+Given estoy intentando bajar mi suscripcion
+And tengo recursos que exceden los limites del nuevo plan
+Then deberia ver la alerta de advertencia de downgrade
+And deberia ver el titulo de advertencia
+And deberia ver la descripcion de advertencia
+And deberia ver la lista de recursos sobre el limite
+And deberia ver el boton de confirmar downgrade
+And deberia ver el boton de cancelar
+```
+
+### Expected Results
+- `downgrade-warning` selector exists
+- `downgrade-warning-title` selector exists
+- `downgrade-warning-description` selector exists
+- `downgrade-warning-list` selector exists
+- `downgrade-limit-{slug}` selectors exist
+- `downgrade-warning-confirm` selector exists
+- `downgrade-warning-cancel` selector exists
+
+### Notes
+DowngradeWarning only renders when `overLimitResources.length > 0`.
+
+---
+
+## @test SEL_BILL_DOC: Selector Documentation
+
+### Metadata
+- **Priority:** Low
+- **Type:** Documentation
+- **Tags:** billing, documentation
+- **Grep:** `@ui-selectors` `@SEL_BILL_DOC`
+- **Status:** Active
+
+```gherkin:en
+Scenario: Document all billing component selectors
+
+Given the billing selector tests are running
+Then the test should log all available billing selectors
+And document which permissions/states are required for each
+```
+
+```gherkin:es
+Scenario: Documentar todos los selectores de componentes de billing
+
+Given los tests de selectores de billing estan corriendo
+Then el test deberia loguear todos los selectores de billing disponibles
+And documentar que permisos/estados se requieren para cada uno
+```
+
+### Expected Results
+- Test logs all billing selectors for reference
+- Documents permission and state requirements

package/tests/cypress/e2e/_utils/selectors/billing.cy.ts

@@ -0,0 +1,182 @@
+/**
+ * UI Selectors Validation: Billing Components
+ *
+ * This test validates that billing component selectors exist in the DOM.
+ * This is a lightweight test that ONLY checks selector presence, not functionality.
+ *
+ * Purpose:
+ * - Validate billing component selectors (ManageBillingButton, SubscriptionStatus, etc.)
+ * - Document selectors from CORE_SELECTORS.settings.billing
+ * - Run as Phase 12 sub-gate before functional tests
+ *
+ * Scope:
+ * - Billing page requires 'settings.billing' permission (OWNER role only)
+ * - Most tests are skipped due to permission/state requirements
+ * - Fast execution (< 30 seconds per describe block)
+ *
+ * Test IDs:
+ * - SEL_BILL_001: Billing Page Structure (skipped - requires OWNER permission)
+ * - SEL_BILL_002: Invoices Section (skipped - requires OWNER permission)
+ * - SEL_BILL_003: Usage Display (skipped - requires OWNER permission)
+ * - SEL_BILL_004: ManageBillingButton (skipped - requires paid subscription)
+ * - SEL_BILL_005: SubscriptionStatus (skipped - requires active subscription)
+ * - SEL_BILL_006: DowngradeWarning (skipped - requires downgrade flow)
+ *
+ * IMPORTANT: Billing page requires 'settings.billing' permission which only OWNER role has.
+ * Users without this permission are redirected to /dashboard/settings.
+ * See also: settings-billing.cy.ts for additional billing selectors.
+ */
+
+describe('Billing Selectors Validation', { tags: ['@ui-selectors', '@billing'] }, () => {
+  // ============================================
+  // SEL_BILL_001: BILLING PAGE STRUCTURE
+  // ============================================
+  describe('SEL_BILL_001: Billing Page Structure', { tags: '@SEL_BILL_001' }, () => {
+    // NOTE: Billing page requires 'settings.billing' permission (OWNER role only)
+    // Default test users may not have this permission
+
+    it.skip('should find billing main container (requires OWNER permission)', () => {
+      cy.get('[data-cy="billing-main"]').should('exist')
+    })
+
+    it.skip('should find billing header (requires OWNER permission)', () => {
+      cy.get('[data-cy="billing-header"]').should('exist')
+    })
+
+    it.skip('should find upgrade plan button (requires OWNER permission)', () => {
+      cy.get('[data-cy="billing-upgrade-plan"]').should('exist')
+    })
+
+    it.skip('should find add payment button (requires OWNER permission)', () => {
+      cy.get('[data-cy="billing-add-payment"]').should('exist')
+    })
+  })
+
+  // ============================================
+  // SEL_BILL_002: INVOICES SECTION
+  // ============================================
+  describe('SEL_BILL_002: Invoices Section', { tags: '@SEL_BILL_002' }, () => {
+    it.skip('should find invoices table (requires OWNER permission)', () => {
+      cy.get('[data-cy="invoices-table"]').should('exist')
+    })
+
+    it.skip('should find invoices row (requires invoices)', () => {
+      cy.get('[data-cy="invoices-row"]').should('exist')
+    })
+
+    it.skip('should find load more button (requires many invoices)', () => {
+      cy.get('[data-cy="invoices-load-more"]').should('exist')
+    })
+
+    it.skip('should find invoice status badge (requires invoices)', () => {
+      cy.get('[data-cy="invoice-status-badge"]').should('exist')
+    })
+  })
+
+  // ============================================
+  // SEL_BILL_003: USAGE DISPLAY
+  // ============================================
+  describe('SEL_BILL_003: Usage Display', { tags: '@SEL_BILL_003' }, () => {
+    it.skip('should display usage numbers (requires OWNER permission)', () => {
+      cy.contains(/\d+\s*\/\s*\d+/).should('be.visible')
+    })
+
+    it.skip('should find usage dashboard (requires UsageDashboard component)', () => {
+      cy.get('[data-cy="usage-dashboard"]').should('exist')
+    })
+  })
+
+  // ============================================
+  // SEL_BILL_004: MANAGE BILLING BUTTON
+  // ============================================
+  describe('SEL_BILL_004: ManageBillingButton', { tags: '@SEL_BILL_004' }, () => {
+    // ManageBillingButton only renders when subscription has externalCustomerId
+
+    it.skip('should find manage billing button (requires paid subscription)', () => {
+      cy.get('[data-cy="manage-billing-button"]').should('exist')
+    })
+  })
+
+  // ============================================
+  // SEL_BILL_005: SUBSCRIPTION STATUS
+  // ============================================
+  describe('SEL_BILL_005: SubscriptionStatus', { tags: '@SEL_BILL_005' }, () => {
+    // SubscriptionStatus requires an active subscription
+
+    it.skip('should find subscription status container (requires subscription)', () => {
+      cy.get('[data-cy="subscription-status"]').should('exist')
+    })
+
+    it.skip('should find subscription plan name (requires subscription)', () => {
+      cy.get('[data-cy="subscription-status-plan"]').should('exist')
+    })
+
+    it.skip('should find subscription status badge (requires subscription)', () => {
+      cy.get('[data-cy="subscription-status-badge"]').should('exist')
+    })
+  })
+
+  // ============================================
+  // SEL_BILL_006: DOWNGRADE WARNING
+  // ============================================
+  describe('SEL_BILL_006: DowngradeWarning', { tags: '@SEL_BILL_006' }, () => {
+    // DowngradeWarning only renders when overLimitResources.length > 0
+
+    it.skip('should find downgrade warning (requires downgrade flow)', () => {
+      cy.get('[data-cy="downgrade-warning"]').should('exist')
+    })
+
+    it.skip('should find downgrade warning title (requires downgrade flow)', () => {
+      cy.get('[data-cy="downgrade-warning-title"]').should('exist')
+    })
+
+    it.skip('should find downgrade warning description (requires downgrade flow)', () => {
+      cy.get('[data-cy="downgrade-warning-description"]').should('exist')
+    })
+
+    it.skip('should find downgrade warning list (requires downgrade flow)', () => {
+      cy.get('[data-cy="downgrade-warning-list"]').should('exist')
+    })
+
+    it.skip('should find downgrade confirm button (requires downgrade flow)', () => {
+      cy.get('[data-cy="downgrade-warning-confirm"]').should('exist')
+    })
+
+    it.skip('should find downgrade cancel button (requires downgrade flow)', () => {
+      cy.get('[data-cy="downgrade-warning-cancel"]').should('exist')
+    })
+  })
+
+  // ============================================
+  // DOCUMENTATION TEST
+  // ============================================
+  describe('SEL_BILL_DOC: Selector Documentation', { tags: '@SEL_BILL_DOC' }, () => {
+    it('should document billing component selectors', () => {
+      cy.log('=== BILLING COMPONENT SELECTORS ===')
+      cy.log('')
+      cy.log('Billing Page (requires OWNER permission):')
+      cy.log('- billing-main, billing-header')
+      cy.log('- billing-upgrade-plan, billing-add-payment')
+      cy.log('- invoices-table, invoices-row, invoices-load-more')
+      cy.log('')
+      cy.log('ManageBillingButton (requires paid subscription):')
+      cy.log('- manage-billing-button')
+      cy.log('')
+      cy.log('SubscriptionStatus (requires active subscription):')
+      cy.log('- subscription-status, subscription-status-plan')
+      cy.log('- subscription-status-badge, subscription-status-period')
+      cy.log('- subscription-status-upgrade, subscription-manage-billing')
+      cy.log('')
+      cy.log('DowngradeWarning (requires downgrade flow):')
+      cy.log('- downgrade-warning, downgrade-warning-title')
+      cy.log('- downgrade-warning-description, downgrade-warning-list')
+      cy.log('- downgrade-limit-{slug}, downgrade-warning-policy')
+      cy.log('- downgrade-warning-confirm, downgrade-warning-cancel')
+      cy.log('')
+      cy.log('UsageDashboard:')
+      cy.log('- usage-dashboard, usage-dashboard-limits')
+      cy.log('- usage-dashboard-limit-{slug}, usage-bar-{slug}')
+      cy.wrap(true).should('be.true')
+    })
+  })
+})