@nextsparkjs/theme-default 0.1.0-beta.20 → 0.1.0-beta.21

package/tests/cypress/e2e/api/devtools/registries.bdd.md

@@ -0,0 +1,300 @@
+---
+feature: DevTools Registries API
+priority: high
+tags: [api, feat-devtools, security, regression]
+grepTags: ["@api", "@feat-devtools"]
+coverage: 16 tests
+---
+
+# DevTools Registries API
+
+> API tests for the DevTools registry endpoints that provide access to features, flows, blocks, and testing registries. These endpoints require superadmin or developer user role for access.
+
+## Endpoints Covered
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/devtools/features` | GET | Feature registry with test coverage |
+| `/api/v1/devtools/flows` | GET | Flow registry (user journeys) |
+| `/api/v1/devtools/blocks` | GET | Block registry with field definitions |
+| `/api/v1/devtools/testing` | GET | Complete tags registry |
+
+---
+
+## @test DEVTOOLS_API_001: Features Registry Access
+
+### Metadata
+- **Priority:** Critical
+- **Type:** Smoke
+- **Tags:** api, devtools, features, authentication
+- **Grep:** `@smoke @feat-devtools`
+
+```gherkin:en
+Scenario: Superadmin can access features registry
+
+Given I have a valid superadmin API key
+When I make a GET request to /api/v1/devtools/features
+Then the response status should be 200
+And the response body should have success true
+And the data should contain features array
+And the data should contain summary with total, withTests, withoutTests
+And the data should contain meta with theme and generatedAt
+```
+
+```gherkin:es
+Scenario: Superadmin puede acceder al registro de features
+
+Given tengo una API key de superadmin válida
+When hago una solicitud GET a /api/v1/devtools/features
+Then el status de respuesta debería ser 200
+And el body debería tener success true
+And los datos deberían contener un array de features
+And los datos deberían contener summary con total, withTests, withoutTests
+And los datos deberían contener meta con theme y generatedAt
+```
+
+### Expected Results
+- Status: 200 OK
+- Response contains features array
+- Summary includes coverage statistics
+- Meta includes theme and generation timestamp
+
+---
+
+## @test DEVTOOLS_API_002: Authentication Required (Features)
+
+### Metadata
+- **Priority:** Critical
+- **Type:** Security
+- **Tags:** api, devtools, authentication, 401
+
+```gherkin:en
+Scenario: Request without API key returns 401
+
+Given I make a request without authentication
+When I make a GET request to /api/v1/devtools/features
+Then the response status should be 401
+And the response body should have success false
+And the error code should be AUTHENTICATION_REQUIRED
+```
+
+```gherkin:es
+Scenario: Solicitud sin API key retorna 401
+
+Given hago una solicitud sin autenticación
+When hago una solicitud GET a /api/v1/devtools/features
+Then el status de respuesta debería ser 401
+And el body debería tener success false
+And el código de error debería ser AUTHENTICATION_REQUIRED
+```
+
+---
+
+## @test DEVTOOLS_API_003: Invalid API Key (Features)
+
+### Metadata
+- **Priority:** Critical
+- **Type:** Security
+- **Tags:** api, devtools, authentication, invalid-key
+
+```gherkin:en
+Scenario: Invalid API key returns 401
+
+Given I have an invalid API key
+When I make a GET request to /api/v1/devtools/features
+Then the response status should be 401
+And the response body should have success false
+```
+
+```gherkin:es
+Scenario: API key inválida retorna 401
+
+Given tengo una API key inválida
+When hago una solicitud GET a /api/v1/devtools/features
+Then el status de respuesta debería ser 401
+And el body debería tener success false
+```
+
+---
+
+## @test DEVTOOLS_API_004: Flows Registry Access
+
+### Metadata
+- **Priority:** Critical
+- **Type:** Smoke
+- **Tags:** api, devtools, flows
+
+```gherkin:en
+Scenario: Superadmin can access flows registry
+
+Given I have a valid superadmin API key
+When I make a GET request to /api/v1/devtools/flows
+Then the response status should be 200
+And the data should contain flows array
+And the data should contain summary with total, withTests, withoutTests
+```
+
+```gherkin:es
+Scenario: Superadmin puede acceder al registro de flows
+
+Given tengo una API key de superadmin válida
+When hago una solicitud GET a /api/v1/devtools/flows
+Then el status de respuesta debería ser 200
+And los datos deberían contener un array de flows
+And los datos deberían contener summary con total, withTests, withoutTests
+```
+
+---
+
+## @test DEVTOOLS_API_007: Blocks Registry Access
+
+### Metadata
+- **Priority:** Critical
+- **Type:** Smoke
+- **Tags:** api, devtools, blocks
+
+```gherkin:en
+Scenario: Superadmin can access blocks registry
+
+Given I have a valid superadmin API key
+When I make a GET request to /api/v1/devtools/blocks
+Then the response status should be 200
+And the data should contain blocks array
+And each block should have slug, name, category, and testing properties
+And the summary should contain categories array
+```
+
+```gherkin:es
+Scenario: Superadmin puede acceder al registro de blocks
+
+Given tengo una API key de superadmin válida
+When hago una solicitud GET a /api/v1/devtools/blocks
+Then el status de respuesta debería ser 200
+And los datos deberían contener un array de blocks
+And cada block debería tener propiedades slug, name, category y testing
+And el summary debería contener un array de categories
+```
+
+---
+
+## @test DEVTOOLS_API_010: Testing Registry Access
+
+### Metadata
+- **Priority:** Critical
+- **Type:** Smoke
+- **Tags:** api, devtools, testing, tags
+
+```gherkin:en
+Scenario: Superadmin can access testing/tags registry
+
+Given I have a valid superadmin API key
+When I make a GET request to /api/v1/devtools/testing
+Then the response status should be 200
+And the data should contain tags object
+And the summary should contain totalTags and testFiles
+And the summary should contain byCategory object
+And the summary should contain features and flows statistics
+```
+
+```gherkin:es
+Scenario: Superadmin puede acceder al registro de testing/tags
+
+Given tengo una API key de superadmin válida
+When hago una solicitud GET a /api/v1/devtools/testing
+Then el status de respuesta debería ser 200
+And los datos deberían contener un objeto tags
+And el summary debería contener totalTags y testFiles
+And el summary debería contener objeto byCategory
+And el summary debería contener estadísticas de features y flows
+```
+
+---
+
+## Response Format
+
+### Success Response (200)
+
+```json
+{
+  "success": true,
+  "data": {
+    "features|flows|blocks|tags": [...],
+    "summary": {
+      "total": 0,
+      "withTests": 0,
+      "withoutTests": 0
+    },
+    "meta": {
+      "theme": "default",
+      "generatedAt": "2025-12-29T00:00:00.000Z"
+    }
+  }
+}
+```
+
+### Error Response (401)
+
+```json
+{
+  "success": false,
+  "error": {
+    "message": "Authentication required",
+    "code": "AUTHENTICATION_REQUIRED",
+    "details": {
+      "hint": "Provide a valid API key via Authorization header or x-api-key header"
+    }
+  }
+}
+```
+
+### Error Response (403) - Member Role
+
+```json
+{
+  "success": false,
+  "error": {
+    "message": "Access denied: DevTools APIs require superadmin or developer role",
+    "code": "DEVTOOLS_ACCESS_DENIED",
+    "details": {
+      "requiredRoles": ["superadmin", "developer"],
+      "hint": "User role \"member\" cannot access DevTools APIs regardless of team role"
+    }
+  }
+}
+```
+
+---
+
+## Test Summary
+
+| Test ID | Endpoint | Description | Tags |
+|---------|----------|-------------|------|
+| DEVTOOLS_API_001 | /features | Success with superadmin key | `@smoke` |
+| DEVTOOLS_API_002 | /features | 401 without auth | |
+| DEVTOOLS_API_003 | /features | 401 with invalid key | |
+| DEVTOOLS_API_004 | /flows | Success with superadmin key | `@smoke` |
+| DEVTOOLS_API_005 | /flows | 401 without auth | |
+| DEVTOOLS_API_006 | /flows | 401 with invalid key | |
+| DEVTOOLS_API_007 | /blocks | Success with superadmin key | `@smoke` |
+| DEVTOOLS_API_008 | /blocks | 401 without auth | |
+| DEVTOOLS_API_009 | /blocks | 401 with invalid key | |
+| DEVTOOLS_API_010 | /testing | Success with superadmin key | `@smoke` |
+| DEVTOOLS_API_011 | /testing | 401 without auth | |
+| DEVTOOLS_API_012 | /testing | 401 with invalid key | |
+| - | All | Response format consistency | |
+
+---
+
+## Environment Variables Required
+
+| Variable | Description |
+|----------|-------------|
+| `SUPERADMIN_API_KEY` | API key for superadmin user |
+
+---
+
+## Security Notes
+
+1. **Role-based access**: Only `superadmin` and `developer` user roles can access these endpoints
+2. **Member restriction**: Users with `member` role are denied regardless of their team role
+3. **API key validation**: Invalid or missing API keys return 401 Unauthorized

package/tests/cypress/e2e/api/devtools/registries.cy.ts

@@ -0,0 +1,368 @@
+/// <reference types="cypress" />
+
+/**
+ * DevTools Registries API Tests
+ *
+ * Tests for the devtools registry endpoints:
+ * - GET /api/v1/devtools/features
+ * - GET /api/v1/devtools/flows
+ * - GET /api/v1/devtools/blocks
+ * - GET /api/v1/devtools/testing
+ *
+ * These endpoints require superadmin or developer user role.
+ * Member role users are NOT allowed regardless of team role.
+ */
+
+import * as allure from 'allure-cypress'
+
+describe('DevTools Registries API', {
+  tags: ['@api', '@feat-devtools', '@security', '@regression']
+}, () => {
+  const BASE_URL = Cypress.config('baseUrl') || 'http://localhost:5173'
+
+  // Superadmin API key for testing (same as other API tests)
+  const SUPERADMIN_API_KEY = 'test_api_key_for_testing_purposes_only_not_a_real_secret_key_abc123'
+  const INVALID_API_KEY = 'test_invalid_key_placeholder_does_not_exist_00000'
+
+  /**
+   * Helper to build headers with API key
+   */
+  const getHeaders = (apiKey: string | null) => {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json'
+    }
+    if (apiKey) {
+      headers['Authorization'] = `Bearer ${apiKey}`
+    }
+    return headers
+  }
+
+  beforeEach(() => {
+    allure.epic('API')
+    allure.feature('DevTools')
+  })
+
+  // ============================================================
+  // GET /api/v1/devtools/features
+  // ============================================================
+  describe('GET /api/v1/devtools/features', () => {
+    const endpoint = '/api/v1/devtools/features'
+
+    beforeEach(() => {
+      allure.story('Features Registry')
+    })
+
+    it('DEVTOOLS_API_001: Should return features registry with valid superadmin API key', { tags: '@smoke' }, () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(SUPERADMIN_API_KEY),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(200)
+        expect(response.body).to.have.property('success', true)
+        expect(response.body).to.have.property('data')
+
+        // Validate data structure
+        const { data } = response.body
+        expect(data).to.have.property('features')
+        expect(data.features).to.be.an('array')
+        expect(data).to.have.property('summary')
+        expect(data.summary).to.have.property('total')
+        expect(data.summary).to.have.property('withTests')
+        expect(data.summary).to.have.property('withoutTests')
+        expect(data).to.have.property('meta')
+        expect(data.meta).to.have.property('theme')
+        expect(data.meta).to.have.property('generatedAt')
+
+        cy.log(`Features: ${data.features.length}, Theme: ${data.meta.theme}`)
+      })
+    })
+
+    it('DEVTOOLS_API_002: Should return 401 without authentication', () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(null),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+        expect(response.body).to.have.property('success', false)
+        expect(response.body).to.have.property('error')
+        expect(response.body.error).to.have.property('code', 'AUTHENTICATION_REQUIRED')
+      })
+    })
+
+    it('DEVTOOLS_API_003: Should return 401 with invalid API key', () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(INVALID_API_KEY),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+        expect(response.body).to.have.property('success', false)
+      })
+    })
+  })
+
+  // ============================================================
+  // GET /api/v1/devtools/flows
+  // ============================================================
+  describe('GET /api/v1/devtools/flows', () => {
+    const endpoint = '/api/v1/devtools/flows'
+
+    beforeEach(() => {
+      allure.story('Flows Registry')
+    })
+
+    it('DEVTOOLS_API_004: Should return flows registry with valid superadmin API key', { tags: '@smoke' }, () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(SUPERADMIN_API_KEY),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(200)
+        expect(response.body).to.have.property('success', true)
+        expect(response.body).to.have.property('data')
+
+        // Validate data structure
+        const { data } = response.body
+        expect(data).to.have.property('flows')
+        expect(data.flows).to.be.an('array')
+        expect(data).to.have.property('summary')
+        expect(data.summary).to.have.property('total')
+        expect(data.summary).to.have.property('withTests')
+        expect(data.summary).to.have.property('withoutTests')
+        expect(data).to.have.property('meta')
+
+        cy.log(`Flows: ${data.flows.length}`)
+      })
+    })
+
+    it('DEVTOOLS_API_005: Should return 401 without authentication', () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(null),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+        expect(response.body).to.have.property('success', false)
+        expect(response.body.error).to.have.property('code', 'AUTHENTICATION_REQUIRED')
+      })
+    })
+
+    it('DEVTOOLS_API_006: Should return 401 with invalid API key', () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(INVALID_API_KEY),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+        expect(response.body).to.have.property('success', false)
+      })
+    })
+  })
+
+  // ============================================================
+  // GET /api/v1/devtools/blocks
+  // ============================================================
+  describe('GET /api/v1/devtools/blocks', () => {
+    const endpoint = '/api/v1/devtools/blocks'
+
+    beforeEach(() => {
+      allure.story('Blocks Registry')
+    })
+
+    it('DEVTOOLS_API_007: Should return blocks registry with valid superadmin API key', { tags: '@smoke' }, () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(SUPERADMIN_API_KEY),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(200)
+        expect(response.body).to.have.property('success', true)
+        expect(response.body).to.have.property('data')
+
+        // Validate data structure
+        const { data } = response.body
+        expect(data).to.have.property('blocks')
+        expect(data.blocks).to.be.an('array')
+        expect(data).to.have.property('summary')
+        expect(data.summary).to.have.property('total')
+        expect(data.summary).to.have.property('withTests')
+        expect(data.summary).to.have.property('withoutTests')
+        expect(data.summary).to.have.property('categories')
+        expect(data.summary.categories).to.be.an('array')
+        expect(data).to.have.property('meta')
+
+        // Validate block structure if any blocks exist
+        if (data.blocks.length > 0) {
+          const block = data.blocks[0]
+          expect(block).to.have.property('slug')
+          expect(block).to.have.property('name')
+          expect(block).to.have.property('category')
+          expect(block).to.have.property('testing')
+          expect(block.testing).to.have.property('hasTests')
+          expect(block.testing).to.have.property('testCount')
+          expect(block.testing).to.have.property('tag')
+        }
+
+        cy.log(`Blocks: ${data.blocks.length}, Categories: ${data.summary.categories.join(', ')}`)
+      })
+    })
+
+    it('DEVTOOLS_API_008: Should return 401 without authentication', () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(null),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+        expect(response.body).to.have.property('success', false)
+        expect(response.body.error).to.have.property('code', 'AUTHENTICATION_REQUIRED')
+      })
+    })
+
+    it('DEVTOOLS_API_009: Should return 401 with invalid API key', () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(INVALID_API_KEY),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+        expect(response.body).to.have.property('success', false)
+      })
+    })
+  })
+
+  // ============================================================
+  // GET /api/v1/devtools/testing
+  // ============================================================
+  describe('GET /api/v1/devtools/testing', () => {
+    const endpoint = '/api/v1/devtools/testing'
+
+    beforeEach(() => {
+      allure.story('Testing Registry')
+    })
+
+    it('DEVTOOLS_API_010: Should return testing/tags registry with valid superadmin API key', { tags: '@smoke' }, () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(SUPERADMIN_API_KEY),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(200)
+        expect(response.body).to.have.property('success', true)
+        expect(response.body).to.have.property('data')
+
+        // Validate data structure
+        const { data } = response.body
+        expect(data).to.have.property('tags')
+        expect(data.tags).to.be.an('object')
+        expect(data).to.have.property('summary')
+        expect(data.summary).to.have.property('totalTags')
+        expect(data.summary).to.have.property('testFiles')
+        expect(data.summary).to.have.property('byCategory')
+        expect(data.summary.byCategory).to.be.an('object')
+        expect(data.summary).to.have.property('features')
+        expect(data.summary).to.have.property('flows')
+        expect(data).to.have.property('meta')
+
+        cy.log(`Total tags: ${data.summary.totalTags}, Test files: ${data.summary.testFiles}`)
+      })
+    })
+
+    it('DEVTOOLS_API_011: Should return 401 without authentication', () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(null),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+        expect(response.body).to.have.property('success', false)
+        expect(response.body.error).to.have.property('code', 'AUTHENTICATION_REQUIRED')
+      })
+    })
+
+    it('DEVTOOLS_API_012: Should return 401 with invalid API key', () => {
+      allure.severity('critical')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}${endpoint}`,
+        headers: getHeaders(INVALID_API_KEY),
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+        expect(response.body).to.have.property('success', false)
+      })
+    })
+  })
+
+  // ============================================================
+  // Cross-endpoint validation
+  // ============================================================
+  describe('Response Format Consistency', () => {
+    beforeEach(() => {
+      allure.story('Response Format')
+    })
+
+    const endpoints = [
+      '/api/v1/devtools/features',
+      '/api/v1/devtools/flows',
+      '/api/v1/devtools/blocks',
+      '/api/v1/devtools/testing'
+    ]
+
+    endpoints.forEach((endpoint) => {
+      it(`Should have consistent response format for ${endpoint}`, () => {
+        cy.request({
+          method: 'GET',
+          url: `${BASE_URL}${endpoint}`,
+          headers: getHeaders(SUPERADMIN_API_KEY),
+          failOnStatusCode: false
+        }).then((response) => {
+          expect(response.status).to.eq(200)
+
+          // All endpoints should have these common properties
+          expect(response.body).to.have.property('success', true)
+          expect(response.body).to.have.property('data')
+          expect(response.body.data).to.have.property('meta')
+          expect(response.body.data.meta).to.have.property('theme')
+          expect(response.body.data.meta).to.have.property('generatedAt')
+        })
+      })
+    })
+  })
+})