@nextsparkjs/core 0.1.0-beta.1 → 0.1.0-beta.3

package/templates/contents/themes/starter/tests/cypress/src/core/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Core POM exports
+ *
+ * Base classes for building Page Object Models:
+ * - BasePOM: Utility methods for all POMs
+ * - DashboardEntityPOM: Base for entity CRUD POMs
+ * - AuthPOM: Authentication pages POM
+ */
+
+export { BasePOM } from './BasePOM'
+export { DashboardEntityPOM, type EntityConfig } from './DashboardEntityPOM'
+export { AuthPOM, type SignupData } from './AuthPOM'

package/templates/contents/themes/starter/tests/cypress/src/helpers/ApiInterceptor.ts

@@ -0,0 +1,170 @@
+/**
+ * ApiInterceptor - Helper for deterministic waits in Cypress
+ *
+ * Replaces unreliable cy.wait(ms) with cy.intercept() based waits
+ * that wait for actual API responses.
+ *
+ * Basic usage:
+ *   const api = new ApiInterceptor('tasks')
+ *   api.setupCrudIntercepts()
+ *   cy.visit('/dashboard/tasks')
+ *   api.waitForList()
+ *
+ * Usage with custom path:
+ *   const api = new ApiInterceptor({
+ *     slug: 'categories',
+ *     customPath: '/api/v1/post-categories'
+ *   })
+ */
+
+export interface ApiInterceptorConfig {
+  /** Entity slug - used to generate aliases */
+  slug: string
+  /** Custom API path (e.g., '/api/v1/post-categories') */
+  customPath?: string
+}
+
+export class ApiInterceptor {
+  private slug: string
+  private endpoint: string
+
+  constructor(slugOrConfig: string | ApiInterceptorConfig) {
+    if (typeof slugOrConfig === 'string') {
+      this.slug = slugOrConfig
+      this.endpoint = `/api/v1/${slugOrConfig}`
+    } else {
+      this.slug = slugOrConfig.slug
+      this.endpoint = slugOrConfig.customPath || `/api/v1/${slugOrConfig.slug}`
+    }
+  }
+
+  // ============================================
+  // ACCESSORS
+  // ============================================
+
+  /** Get the API endpoint path */
+  get path(): string {
+    return this.endpoint
+  }
+
+  /** Get the entity slug */
+  get entitySlug(): string {
+    return this.slug
+  }
+
+  /** Get alias names for all operations */
+  get aliases() {
+    return {
+      list: `${this.slug}List`,
+      create: `${this.slug}Create`,
+      update: `${this.slug}Update`,
+      delete: `${this.slug}Delete`
+    }
+  }
+
+  // ============================================
+  // INTERCEPT SETUP
+  // ============================================
+
+  /**
+   * Setup intercepts for all CRUD operations
+   * Call this BEFORE navigation in beforeEach or at test start
+   */
+  setupCrudIntercepts(): this {
+    cy.intercept('GET', `${this.endpoint}*`).as(this.aliases.list)
+    cy.intercept('POST', this.endpoint).as(this.aliases.create)
+    cy.intercept('PATCH', `${this.endpoint}/*`).as(this.aliases.update)
+    cy.intercept('DELETE', `${this.endpoint}/*`).as(this.aliases.delete)
+    return this
+  }
+
+  /**
+   * Setup only list + create intercepts
+   * Useful for list pages with inline create
+   */
+  setupListIntercepts(): this {
+    cy.intercept('GET', `${this.endpoint}*`).as(this.aliases.list)
+    cy.intercept('POST', this.endpoint).as(this.aliases.create)
+    return this
+  }
+
+  // ============================================
+  // WAIT METHODS
+  // ============================================
+
+  /**
+   * Wait for list response (GET)
+   * Use after navigation or after mutations to wait for refresh
+   */
+  waitForList(timeout = 10000): Cypress.Chainable {
+    return cy.wait(`@${this.aliases.list}`, { timeout })
+  }
+
+  /**
+   * Wait for create response (POST) and validate success status
+   */
+  waitForCreate(timeout = 10000): Cypress.Chainable {
+    return cy.wait(`@${this.aliases.create}`, { timeout })
+      .its('response.statusCode')
+      .should('be.oneOf', [200, 201])
+  }
+
+  /**
+   * Wait for update response (PATCH) and validate success status
+   */
+  waitForUpdate(timeout = 10000): Cypress.Chainable {
+    return cy.wait(`@${this.aliases.update}`, { timeout })
+      .its('response.statusCode')
+      .should('be.oneOf', [200, 201])
+  }
+
+  /**
+   * Wait for delete response (DELETE) and validate success status
+   */
+  waitForDelete(timeout = 10000): Cypress.Chainable {
+    return cy.wait(`@${this.aliases.delete}`, { timeout })
+      .its('response.statusCode')
+      .should('be.oneOf', [200, 204])
+  }
+
+  // ============================================
+  // CONVENIENCE METHODS
+  // ============================================
+
+  /**
+   * Wait for list refresh (alias for waitForList)
+   * Semantic name for use after create/update/delete
+   */
+  waitForRefresh(timeout = 10000): Cypress.Chainable {
+    return this.waitForList(timeout)
+  }
+
+  /**
+   * Wait for create + list refresh
+   * Common pattern: create entity, wait for success, wait for list to refresh
+   */
+  waitForCreateAndRefresh(timeout = 10000): Cypress.Chainable {
+    this.waitForCreate(timeout)
+    return this.waitForList(timeout)
+  }
+
+  /**
+   * Wait for update + list refresh
+   * Common pattern: update entity, wait for success, wait for list to refresh
+   */
+  waitForUpdateAndRefresh(timeout = 10000): Cypress.Chainable {
+    this.waitForUpdate(timeout)
+    return this.waitForList(timeout)
+  }
+
+  /**
+   * Wait for delete + list refresh
+   * Common pattern: delete entity, wait for success, wait for list to refresh
+   */
+  waitForDeleteAndRefresh(timeout = 10000): Cypress.Chainable {
+    this.waitForDelete(timeout)
+    return this.waitForList(timeout)
+  }
+}
+
+export default ApiInterceptor

package/templates/contents/themes/starter/tests/cypress/src/selectors.ts

@@ -0,0 +1,155 @@
+/**
+ * Starter Theme Selectors
+ *
+ * Theme-level selector configuration that extends core selectors.
+ * This is the single source of truth for Cypress tests in this theme.
+ *
+ * Architecture:
+ * - Core selectors: `core/lib/test/core-selectors.ts`
+ * - Theme selectors: This file (can extend core)
+ * - POMs import: `import { cySelector } from '../selectors'`
+ *
+ * @example POM usage:
+ * ```typescript
+ * import { cySelector, sel, SELECTORS } from '../selectors'
+ *
+ * class MyPOM extends BasePOM {
+ *   get elements() {
+ *     return {
+ *       loginForm: cySelector('auth.login.form'),
+ *       submitButton: cySelector('auth.login.submit'),
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Extending with theme-specific selectors:
+ * ```typescript
+ * const THEME_SELECTORS = {
+ *   ...CORE_SELECTORS,
+ *   myThemeFeature: {
+ *     button: 'theme-specific-button',
+ *     modal: 'theme-specific-modal',
+ *   }
+ * }
+ * ```
+ */
+
+import { createSelectorHelpers, CORE_SELECTORS } from '@nextsparkjs/core/lib/test'
+
+// =============================================================================
+// THEME SELECTORS
+// =============================================================================
+
+/**
+ * Theme selectors extending core.
+ *
+ * Add theme-specific selectors here. For example:
+ *
+ * const THEME_SELECTORS = {
+ *   ...CORE_SELECTORS,
+ *   themeSpecific: {
+ *     specialButton: 'theme-special-btn',
+ *   }
+ * }
+ */
+const THEME_SELECTORS = {
+  ...CORE_SELECTORS,
+  // Starter theme specific selectors
+  auth: {
+    ...CORE_SELECTORS.auth,
+    // Add any starter-specific auth selectors here
+  },
+  tasks: {
+    list: 'tasks-list',
+    item: 'task-item',
+    createButton: 'create-task-button',
+    form: 'task-form',
+    titleInput: 'task-title-input',
+    descriptionInput: 'task-description-input',
+    statusSelect: 'task-status-select',
+    prioritySelect: 'task-priority-select',
+    submitButton: 'task-submit-button',
+    cancelButton: 'task-cancel-button',
+    deleteButton: 'task-delete-button',
+    editButton: 'task-edit-button',
+    searchInput: 'tasks-search-input',
+    filterStatus: 'tasks-filter-status',
+    filterPriority: 'tasks-filter-priority',
+  },
+  analytics: {
+    page: 'analytics-page',
+    statsCard: 'stats-card',
+    tasksChart: 'tasks-chart',
+    recentActivity: 'recent-activity',
+    totalTasks: 'total-tasks-stat',
+    completedTasks: 'completed-tasks-stat',
+    pendingTasks: 'pending-tasks-stat',
+  },
+} as const
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+/**
+ * Create helpers bound to theme selectors
+ */
+const helpers = createSelectorHelpers(THEME_SELECTORS)
+
+/**
+ * Full selectors object (core + theme extensions)
+ */
+export const SELECTORS = helpers.SELECTORS
+
+/**
+ * Get a selector value by path
+ *
+ * @example
+ * sel('auth.login.form') // 'login-form'
+ * sel('entities.table.row', { slug: 'customers', id: '123' }) // 'customers-row-123'
+ */
+export const sel = helpers.sel
+
+/**
+ * Alias for sel
+ */
+export const s = helpers.s
+
+/**
+ * Get selector only in dev/test environments
+ */
+export const selDev = helpers.selDev
+
+/**
+ * Get Cypress selector string [data-cy="..."]
+ *
+ * @example
+ * cySelector('auth.login.form') // '[data-cy="login-form"]'
+ * cySelector('entities.table.row', { slug: 'customers', id: '123' }) // '[data-cy="customers-row-123"]'
+ */
+export const cySelector = helpers.cySelector
+
+/**
+ * Create entity-specific selector helpers
+ *
+ * @example
+ * const taskSel = entitySelectors('tasks')
+ * taskSel.row('abc123') // 'tasks-row-abc123'
+ */
+export const entitySelectors = helpers.entitySelectors
+
+/**
+ * Type for the selectors object
+ */
+export type ThemeSelectorsType = typeof THEME_SELECTORS
+
+/**
+ * Re-export types
+ */
+export type { Replacements } from '@nextsparkjs/core/lib/test'
+
+/**
+ * Re-export CORE_SELECTORS for reference
+ */
+export { CORE_SELECTORS }

package/templates/contents/themes/starter/tests/cypress/src/session-helpers.ts

@@ -0,0 +1,255 @@
+/**
+ * Starter Theme Session Helpers
+ *
+ * Direct login functions for theme tests using theme-specific users.
+ * These helpers don't depend on ACTIVE_THEME environment variable.
+ *
+ * IMPORTANT: After login, this helper sets activeTeamId in localStorage.
+ * This is required because all entity API calls include x-team-id header
+ * which is read from localStorage.activeTeamId.
+ */
+
+/**
+ * Theme Test Users
+ * These emails should match the seeded users for the starter theme
+ */
+export const THEME_USERS = {
+  OWNER: 'owner@starter.dev',
+  ADMIN: 'admin@starter.dev',
+  MEMBER: 'member@starter.dev',
+  VIEWER: 'viewer@starter.dev',
+} as const
+
+// Common password for all test users
+const TEST_PASSWORD = 'Test1234'
+
+// Extended timeout for dev server compilation
+const API_TIMEOUT = 30000
+
+/**
+ * Sets up team context after login (requires page to be loaded for localStorage access)
+ *
+ * This is CRITICAL for entity API calls to work:
+ * 1. Fetches user's teams from /api/v1/teams
+ * 2. Sets activeTeamId in localStorage (used by frontend to add x-team-id header)
+ * 3. Calls /api/v1/teams/switch to set server-side team cookie
+ *
+ * Without this, all entity API calls return 400 "Team context required"
+ */
+function setupTeamContext() {
+  cy.request({
+    method: 'GET',
+    url: '/api/v1/teams',
+    timeout: API_TIMEOUT,
+    failOnStatusCode: false
+  }).then((teamsResponse) => {
+    if (teamsResponse.status === 200 && teamsResponse.body?.data?.length > 0) {
+      const firstTeam = teamsResponse.body.data[0]
+      const teamId = firstTeam.id
+
+      cy.log(`Setting active team: ${firstTeam.name} (${teamId})`)
+
+      // Set in localStorage (used by frontend buildHeaders() to add x-team-id)
+      cy.window().then((win) => {
+        win.localStorage.setItem('activeTeamId', teamId)
+      })
+
+      // Call teams/switch to set server-side cookie (for SSR/layouts)
+      cy.request({
+        method: 'POST',
+        url: '/api/v1/teams/switch',
+        body: { teamId },
+        timeout: API_TIMEOUT,
+        failOnStatusCode: false
+      })
+    } else {
+      cy.log(`Warning: No teams found for user, API calls requiring team context will fail`)
+    }
+  })
+}
+
+/**
+ * Login via API (faster and more stable than UI)
+ * Returns true if API login succeeded, false if fallback to UI was needed.
+ */
+function apiLogin(email: string): Cypress.Chainable<boolean> {
+  return cy.request({
+    method: 'POST',
+    url: '/api/auth/sign-in/email',
+    body: { email, password: TEST_PASSWORD },
+    timeout: API_TIMEOUT,
+    failOnStatusCode: false
+  }).then((response) => {
+    if (response.status === 200) {
+      return true
+    } else {
+      cy.log(`Warning: API login failed with status ${response.status}, falling back to UI login`)
+      // Fallback to UI login if API fails
+      cy.visit('/login', { timeout: 60000 })
+      return false
+    }
+  })
+}
+
+/**
+ * Login as Owner
+ * Session is cached and reused across tests
+ */
+export function loginAsOwner() {
+  cy.session('owner-session', () => {
+    apiLogin(THEME_USERS.OWNER).then((apiLoginSucceeded) => {
+      if (apiLoginSucceeded) {
+        cy.visit('/dashboard', { timeout: 60000 })
+      }
+      cy.url().should('include', '/dashboard')
+      setupTeamContext()
+    })
+  }, {
+    validate: () => {
+      cy.request({
+        url: '/api/auth/get-session',
+        timeout: API_TIMEOUT,
+        failOnStatusCode: false
+      }).its('status').should('eq', 200)
+
+      cy.window().then((win) => {
+        const teamId = win.localStorage.getItem('activeTeamId')
+        expect(teamId, 'activeTeamId should exist in localStorage').to.not.be.null
+        expect(teamId, 'activeTeamId should not be empty').to.not.be.empty
+      })
+    }
+  })
+}
+
+/**
+ * Login as Admin
+ * Session is cached and reused across tests
+ */
+export function loginAsAdmin() {
+  cy.session('admin-session', () => {
+    apiLogin(THEME_USERS.ADMIN).then((apiLoginSucceeded) => {
+      if (apiLoginSucceeded) {
+        cy.visit('/dashboard', { timeout: 60000 })
+      }
+      cy.url().should('include', '/dashboard')
+      setupTeamContext()
+    })
+  }, {
+    validate: () => {
+      cy.request({
+        url: '/api/auth/get-session',
+        timeout: API_TIMEOUT,
+        failOnStatusCode: false
+      }).its('status').should('eq', 200)
+    }
+  })
+}
+
+/**
+ * Login as Member
+ * Session is cached and reused across tests
+ */
+export function loginAsMember() {
+  cy.session('member-session', () => {
+    apiLogin(THEME_USERS.MEMBER).then((apiLoginSucceeded) => {
+      if (apiLoginSucceeded) {
+        cy.visit('/dashboard', { timeout: 60000 })
+      }
+      cy.url().should('include', '/dashboard')
+      setupTeamContext()
+    })
+  }, {
+    validate: () => {
+      cy.request({
+        url: '/api/auth/get-session',
+        timeout: API_TIMEOUT,
+        failOnStatusCode: false
+      }).its('status').should('eq', 200)
+    }
+  })
+}
+
+/**
+ * Login as Viewer
+ * Session is cached and reused across tests
+ */
+export function loginAsViewer() {
+  cy.session('viewer-session', () => {
+    apiLogin(THEME_USERS.VIEWER).then((apiLoginSucceeded) => {
+      if (apiLoginSucceeded) {
+        cy.visit('/dashboard', { timeout: 60000 })
+      }
+      cy.url().should('include', '/dashboard')
+      setupTeamContext()
+    })
+  }, {
+    validate: () => {
+      cy.request({
+        url: '/api/auth/get-session',
+        timeout: API_TIMEOUT,
+        failOnStatusCode: false
+      }).its('status').should('eq', 200)
+    }
+  })
+}
+
+/**
+ * Login with custom session management
+ * Useful for specific email/password combinations
+ */
+export function loginWithSession(email: string, password: string) {
+  const sessionId = `session-${email.replace(/[@.]/g, '-')}`
+
+  cy.session(sessionId, () => {
+    cy.request({
+      method: 'POST',
+      url: '/api/auth/sign-in/email',
+      body: { email, password },
+      timeout: API_TIMEOUT,
+      failOnStatusCode: false
+    }).then((response) => {
+      if (response.status === 200) {
+        cy.visit('/dashboard', { timeout: 60000 })
+        cy.url().should('include', '/dashboard')
+        setupTeamContext()
+      } else {
+        throw new Error(`Login failed for ${email}: ${response.body?.error || 'Unknown error'}`)
+      }
+    })
+  })
+}
+
+/**
+ * Login as a specific role
+ */
+export function loginAsRole(role: 'owner' | 'admin' | 'member' | 'viewer') {
+  const loginFunctions = {
+    owner: loginAsOwner,
+    admin: loginAsAdmin,
+    member: loginAsMember,
+    viewer: loginAsViewer,
+  }
+
+  const loginFn = loginFunctions[role]
+  if (loginFn) {
+    loginFn()
+  } else {
+    throw new Error(`Unknown role: ${role}`)
+  }
+}
+
+/**
+ * Clear all session data
+ */
+export function clearSession() {
+  cy.clearCookies()
+  cy.clearLocalStorage()
+  Cypress.session.clearAllSavedSessions()
+}
+
+/**
+ * Returns theme users for backwards compatibility with external helper pattern.
+ */
+export function getThemeUsers() {
+  return THEME_USERS
+}