@nextsparkjs/theme-crm 0.1.0-beta.18 → 0.1.0-beta.20

package/tests/cypress/src/components/StageColumn.js

@@ -0,0 +1,196 @@
+/**
+ * StageColumn - Page Object Model Class
+ *
+ * POM for individual stage columns in the pipeline kanban board.
+ * Handles stage-specific interactions and validations.
+ */
+export class StageColumn {
+  /**
+   * Get selectors for a specific stage
+   * @param {string} stageId - Stage ID
+   */
+  static getStageSelectors(stageId) {
+    return {
+      column: `[data-cy="pipeline-stage-${stageId}"]`,
+      header: `[data-cy="stage-header-${stageId}"]`,
+      title: `[data-cy="stage-title-${stageId}"]`,
+      count: `[data-cy="stage-count-${stageId}"]`,
+      value: `[data-cy="stage-value-${stageId}"]`,
+      deals: `[data-cy="stage-deals-${stageId}"]`,
+      emptyState: `[data-cy="stage-empty-${stageId}"]`,
+      addDealBtn: `[data-cy="stage-add-deal-${stageId}"]`,
+    }
+  }
+
+  /**
+   * @param {string} stageId - The stage ID
+   */
+  constructor(stageId) {
+    this.stageId = stageId
+    this.selectors = StageColumn.getStageSelectors(stageId)
+  }
+
+  /**
+   * Validate stage column is visible
+   */
+  validateVisible() {
+    cy.get(this.selectors.column).should('be.visible')
+    return this
+  }
+
+  /**
+   * Validate stage header is visible
+   */
+  validateHeaderVisible() {
+    cy.get(this.selectors.header).should('be.visible')
+    return this
+  }
+
+  /**
+   * Validate stage title
+   * @param {string} title - Expected title
+   */
+  validateTitle(title) {
+    cy.get(this.selectors.title).should('contain', title)
+    return this
+  }
+
+  /**
+   * Get the deal count in this stage
+   */
+  getDealCount() {
+    return cy.get(this.selectors.column)
+      .find('[data-cy^="deal-card-"]')
+      .its('length')
+  }
+
+  /**
+   * Validate number of deals in this stage
+   * @param {number} count - Expected deal count
+   */
+  validateDealCount(count) {
+    if (count === 0) {
+      this.validateEmpty()
+    } else {
+      cy.get(this.selectors.column)
+        .find('[data-cy^="deal-card-"]')
+        .should('have.length', count)
+    }
+    return this
+  }
+
+  /**
+   * Validate stage count badge
+   * @param {number} count - Expected count
+   */
+  validateCountBadge(count) {
+    cy.get(this.selectors.count).should('contain', count)
+    return this
+  }
+
+  /**
+   * Get the total value in this stage
+   */
+  getTotalValue() {
+    return cy.get(this.selectors.value).invoke('text')
+  }
+
+  /**
+   * Validate total value displayed
+   * @param {string} value - Expected value (e.g., "$50,000")
+   */
+  validateTotalValue(value) {
+    cy.get(this.selectors.value).should('contain', value)
+    return this
+  }
+
+  /**
+   * Validate stage is empty
+   */
+  isEmpty() {
+    return cy.get(this.selectors.emptyState).should('exist')
+  }
+
+  /**
+   * Validate empty state is visible
+   */
+  validateEmpty() {
+    cy.get(this.selectors.emptyState).should('be.visible')
+    return this
+  }
+
+  /**
+   * Validate stage is not empty
+   */
+  validateNotEmpty() {
+    cy.get(this.selectors.emptyState).should('not.exist')
+    cy.get(this.selectors.column)
+      .find('[data-cy^="deal-card-"]')
+      .should('have.length.greaterThan', 0)
+    return this
+  }
+
+  /**
+   * Click add deal button in this stage
+   */
+  addDeal() {
+    cy.get(this.selectors.addDealBtn).click()
+    return this
+  }
+
+  /**
+   * Validate add deal button is visible
+   */
+  validateAddDealVisible() {
+    cy.get(this.selectors.addDealBtn).should('be.visible')
+    return this
+  }
+
+  /**
+   * Get all deals in this stage
+   */
+  getDeals() {
+    return cy.get(this.selectors.column)
+      .find('[data-cy^="deal-card-"]')
+  }
+
+  /**
+   * Validate a specific deal exists in this stage
+   * @param {string} dealId - Deal ID
+   */
+  validateDealExists(dealId) {
+    cy.get(this.selectors.column)
+      .find(`[data-cy="deal-card-${dealId}"]`)
+      .should('exist')
+    return this
+  }
+
+  /**
+   * Validate a specific deal does not exist in this stage
+   * @param {string} dealId - Deal ID
+   */
+  validateDealNotExists(dealId) {
+    cy.get(this.selectors.column)
+      .find(`[data-cy="deal-card-${dealId}"]`)
+      .should('not.exist')
+    return this
+  }
+
+  /**
+   * Get a specific deal card in this stage
+   * @param {string} dealId - Deal ID
+   */
+  getDealCard(dealId) {
+    return cy.get(this.selectors.column)
+      .find(`[data-cy="deal-card-${dealId}"]`)
+  }
+
+  /**
+   * Click a specific deal card in this stage
+   * @param {string} dealId - Deal ID
+   */
+  clickDeal(dealId) {
+    this.getDealCard(dealId).click()
+    return this
+  }
+}

package/tests/cypress/src/components/index.js

@@ -0,0 +1,13 @@
+/**
+ * CRM Theme Components - Export Index
+ *
+ * Exports all CRM theme component POM classes.
+ */
+
+export { CRMSidebar } from './CRMSidebar.js'
+export { CRMTopBar } from './CRMTopBar.js'
+export { CRMMobileNav } from './CRMMobileNav.js'
+export { CRMDataTable } from './CRMDataTable.js'
+export { PipelineKanban } from './PipelineKanban.js'
+export { StageColumn } from './StageColumn.js'
+export { DealCard } from './DealCard.js'

package/tests/cypress/src/components/index.ts

@@ -0,0 +1,22 @@
+/**
+ * CRM Theme - Cypress POM Components
+ *
+ * Export all generic POM classes for CRM entity testing.
+ * These POMs use data-cy selectors from entities.json following
+ * the convention: {slug}-{component}-{detail}
+ */
+
+export { EntityList, type EntityConfig } from './EntityList'
+export { EntityForm } from './EntityForm'
+export { EntityDetail, type EntityDetailConfig } from './EntityDetail'
+
+// Default exports for convenience
+import { EntityList } from './EntityList'
+import { EntityForm } from './EntityForm'
+import { EntityDetail } from './EntityDetail'
+
+export default {
+  EntityList,
+  EntityForm,
+  EntityDetail,
+}

package/tests/cypress/src/controllers/ActivityAPIController.ts

@@ -0,0 +1,113 @@
+/**
+ * ActivityAPIController - TypeScript controller for Activities API
+ *
+ * Handles CRUD operations for /api/v1/activities endpoints
+ */
+
+import { BaseAPIController, APIRequestOptions, APIResponse } from './BaseAPIController'
+
+export interface ActivityData {
+  type?: string
+  subject?: string
+  description?: string
+  dueDate?: string
+  contactId?: string
+  companyId?: string
+  opportunityId?: string
+  completedAt?: string
+  assignedTo?: string
+  status?: string
+}
+
+export interface ActivityGetAllOptions extends APIRequestOptions {
+  type?: string
+  status?: string
+  contactId?: string
+  companyId?: string
+  opportunityId?: string
+  assignedTo?: string
+  completed?: boolean
+}
+
+export class ActivityAPIController extends BaseAPIController {
+  protected entitySlug = 'activities'
+
+  /**
+   * GET all activities with filtering options
+   */
+  getAll(options: ActivityGetAllOptions = {}): Cypress.Chainable<APIResponse> {
+    return super.getAll(options)
+  }
+
+  /**
+   * Mark activity as complete
+   */
+  complete(id: string, options: APIRequestOptions = {}): Cypress.Chainable<APIResponse> {
+    const completedAt = new Date().toISOString()
+    return this.update(id, { completedAt }, options)
+  }
+
+  /**
+   * Reschedule activity to new date
+   */
+  reschedule(id: string, newDate: string, options: APIRequestOptions = {}): Cypress.Chainable<APIResponse> {
+    return this.update(id, { dueDate: newDate }, options)
+  }
+
+  /**
+   * Generate random activity data for testing
+   */
+  generateRandomData(overrides: Partial<ActivityData> = {}): ActivityData {
+    const timestamp = Date.now()
+    const randomId = Math.random().toString(36).substring(2, 8)
+
+    const types = ['call', 'email', 'meeting', 'task', 'note', 'demo', 'presentation']
+    const subjects = [
+      'Initial Discovery Call',
+      'Product Demo',
+      'Follow-up Email',
+      'Contract Review Meeting',
+      'Proposal Presentation',
+      'Stakeholder Introduction'
+    ]
+
+    const daysFromNow = Math.floor(Math.random() * 30) + 1
+    const dueDate = new Date()
+    dueDate.setDate(dueDate.getDate() + daysFromNow)
+
+    const type = types[Math.floor(Math.random() * types.length)]
+    const subject = subjects[Math.floor(Math.random() * subjects.length)]
+
+    return {
+      type,
+      subject: `${subject} - ${randomId}`,
+      description: `Test activity created at ${new Date(timestamp).toISOString()}`,
+      dueDate: dueDate.toISOString(),
+      ...overrides
+    }
+  }
+
+  /**
+   * Validate activity object structure
+   */
+  validateObject(activity: Record<string, unknown>, allowMetas = false): void {
+    this.validateSystemFields(activity)
+
+    expect(activity).to.have.property('type')
+    expect(activity.type).to.be.a('string')
+
+    expect(activity).to.have.property('subject')
+    expect(activity.subject).to.be.a('string')
+
+    this.validateOptionalStringFields(activity, [
+      'description', 'dueDate', 'contactId', 'companyId',
+      'opportunityId', 'completedAt', 'assignedTo'
+    ])
+
+    if (allowMetas && Object.prototype.hasOwnProperty.call(activity, 'metas')) {
+      expect(activity.metas).to.be.an('object')
+    }
+  }
+}
+
+export default ActivityAPIController

package/tests/cypress/src/controllers/BaseAPIController.ts

@@ -0,0 +1,307 @@
+/**
+ * BaseAPIController - Abstract base class for all CRM API controllers
+ *
+ * Provides common functionality for:
+ * - HTTP request handling with authentication
+ * - Response validation
+ * - Test data generation
+ * - Error handling
+ */
+
+export interface APIRequestOptions {
+  headers?: Record<string, string>
+  page?: number
+  limit?: number
+  search?: string
+  metas?: string
+  [key: string]: unknown
+}
+
+export interface APIResponse<T = unknown> {
+  status: number
+  body: {
+    success: boolean
+    data: T
+    info: {
+      page?: number
+      limit?: number
+      total?: number | string
+      totalPages?: number
+      timestamp: string
+    }
+    error?: string
+    code?: string
+  }
+}
+
+export interface CreateTestRecordOptions {
+  withRetry?: boolean
+  maxRetries?: number
+}
+
+export abstract class BaseAPIController {
+  protected baseUrl: string
+  protected apiKey: string | null
+  protected teamId: string | null
+  protected abstract entitySlug: string
+
+  constructor(
+    baseUrl = 'http://localhost:5173',
+    apiKey: string | null = null,
+    teamId: string | null = null
+  ) {
+    this.baseUrl = baseUrl
+    this.apiKey = apiKey
+    this.teamId = teamId
+  }
+
+  /**
+   * Get the API endpoint for this entity
+   */
+  protected get endpoint(): string {
+    return `/api/v1/${this.entitySlug}`
+  }
+
+  /**
+   * Get endpoint for a specific record by ID
+   */
+  protected endpointById(id: string): string {
+    return `${this.endpoint}/${id}`
+  }
+
+  /**
+   * Set the API key for requests
+   */
+  setApiKey(apiKey: string): this {
+    this.apiKey = apiKey
+    return this
+  }
+
+  /**
+   * Set the team ID for requests
+   */
+  setTeamId(teamId: string): this {
+    this.teamId = teamId
+    return this
+  }
+
+  /**
+   * Get default headers for requests
+   */
+  protected getHeaders(additionalHeaders: Record<string, string> = {}): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...additionalHeaders
+    }
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`
+    }
+
+    if (this.teamId) {
+      headers['x-team-id'] = this.teamId
+    }
+
+    return headers
+  }
+
+  /**
+   * Build query string from options
+   */
+  protected buildQueryString(options: Record<string, unknown>): string {
+    const queryParams = new URLSearchParams()
+
+    Object.entries(options).forEach(([key, value]) => {
+      if (value !== undefined && value !== null && key !== 'headers') {
+        queryParams.append(key, String(value))
+      }
+    })
+
+    const queryString = queryParams.toString()
+    return queryString ? `?${queryString}` : ''
+  }
+
+  /**
+   * GET all records with optional filtering
+   */
+  getAll(options: APIRequestOptions = {}): Cypress.Chainable<APIResponse> {
+    const { headers = {}, ...queryOptions } = options
+    const url = `${this.baseUrl}${this.endpoint}${this.buildQueryString(queryOptions)}`
+
+    return cy.request({
+      method: 'GET',
+      url,
+      headers: this.getHeaders(headers),
+      failOnStatusCode: false
+    })
+  }
+
+  /**
+   * GET a single record by ID
+   */
+  getById(id: string, options: APIRequestOptions = {}): Cypress.Chainable<APIResponse> {
+    const { headers = {}, metas } = options
+    const queryParams: Record<string, unknown> = {}
+    if (metas) queryParams.metas = metas
+
+    const url = `${this.baseUrl}${this.endpointById(id)}${this.buildQueryString(queryParams)}`
+
+    return cy.request({
+      method: 'GET',
+      url,
+      headers: this.getHeaders(headers),
+      failOnStatusCode: false
+    })
+  }
+
+  /**
+   * POST create a new record
+   */
+  create(data: Record<string, unknown>, options: APIRequestOptions = {}): Cypress.Chainable<APIResponse> {
+    const { headers = {} } = options
+
+    return cy.request({
+      method: 'POST',
+      url: `${this.baseUrl}${this.endpoint}`,
+      headers: this.getHeaders(headers),
+      body: data,
+      failOnStatusCode: false
+    })
+  }
+
+  /**
+   * PATCH update an existing record
+   */
+  update(id: string, data: Record<string, unknown>, options: APIRequestOptions = {}): Cypress.Chainable<APIResponse> {
+    const { headers = {} } = options
+
+    return cy.request({
+      method: 'PATCH',
+      url: `${this.baseUrl}${this.endpointById(id)}`,
+      headers: this.getHeaders(headers),
+      body: data,
+      failOnStatusCode: false
+    })
+  }
+
+  /**
+   * DELETE a record
+   */
+  delete(id: string, options: APIRequestOptions = {}): Cypress.Chainable<APIResponse> {
+    const { headers = {} } = options
+
+    return cy.request({
+      method: 'DELETE',
+      url: `${this.baseUrl}${this.endpointById(id)}`,
+      headers: this.getHeaders(headers),
+      failOnStatusCode: false
+    })
+  }
+
+  /**
+   * Generate random test data - must be implemented by subclasses
+   */
+  abstract generateRandomData(overrides?: Record<string, unknown>): Record<string, unknown>
+
+  /**
+   * Create a test record with optional retry logic
+   */
+  createTestRecord(
+    data: Record<string, unknown> = {},
+    options: CreateTestRecordOptions = {}
+  ): Cypress.Chainable<Record<string, unknown>> {
+    const { withRetry = false, maxRetries = 3 } = options
+    const testData = this.generateRandomData(data)
+
+    if (withRetry) {
+      return this.createWithRetry(testData, maxRetries)
+    }
+
+    return this.create(testData).then((response) => {
+      if (response.status === 201) {
+        return { ...testData, ...response.body.data }
+      }
+      throw new Error(`Failed to create test record: ${response.body?.error || 'Unknown error'}`)
+    })
+  }
+
+  /**
+   * Create with retry logic for handling transient failures
+   */
+  protected createWithRetry(
+    data: Record<string, unknown>,
+    maxRetries: number,
+    currentAttempt = 1
+  ): Cypress.Chainable<Record<string, unknown>> {
+    return this.create(data).then((response) => {
+      if (response.status === 201) {
+        return { ...data, ...response.body.data }
+      }
+
+      if (response.status === 500 && currentAttempt < maxRetries) {
+        cy.wait(500 * currentAttempt) // Exponential backoff
+        return this.createWithRetry(data, maxRetries, currentAttempt + 1)
+      }
+
+      throw new Error(`Failed to create test record after ${currentAttempt} attempts: ${response.body?.error || 'Unknown error'}`)
+    })
+  }
+
+  /**
+   * Clean up a test record
+   */
+  cleanupTestRecord(id: string): Cypress.Chainable<APIResponse> {
+    return this.delete(id)
+  }
+
+  // ========== VALIDATION METHODS ==========
+
+  /**
+   * Validate success response structure
+   */
+  validateSuccessResponse(response: APIResponse, expectedStatus = 200): void {
+    expect(response.status).to.eq(expectedStatus)
+    expect(response.body).to.have.property('success', true)
+    expect(response.body).to.have.property('data')
+    expect(response.body).to.have.property('info')
+    expect(response.body.info).to.have.property('timestamp')
+  }
+
+  /**
+   * Validate error response structure
+   */
+  validateErrorResponse(response: APIResponse, expectedStatus: number, expectedErrorCode?: string): void {
+    expect(response.status).to.eq(expectedStatus)
+    expect(response.body).to.have.property('success', false)
+    expect(response.body).to.have.property('error')
+
+    if (expectedErrorCode) {
+      expect(response.body).to.have.property('code', expectedErrorCode)
+    }
+  }
+
+  /**
+   * Validate basic object structure - must be implemented by subclasses
+   */
+  abstract validateObject(obj: Record<string, unknown>, allowMetas?: boolean): void
+
+  /**
+   * Validate common system fields present in all entities
+   */
+  protected validateSystemFields(obj: Record<string, unknown>): void {
+    expect(obj).to.have.property('id')
+    expect(obj).to.have.property('createdAt')
+    expect(obj).to.have.property('updatedAt')
+  }
+
+  /**
+   * Helper to validate optional string fields
+   */
+  protected validateOptionalStringFields(obj: Record<string, unknown>, fields: string[]): void {
+    fields.forEach(field => {
+      if (obj[field] !== null && obj[field] !== undefined) {
+        expect(obj[field]).to.be.a('string')
+      }
+    })
+  }
+}