@priscilla-ai/vue 1.0.5 → 1.0.7

package/src/__tests__/PriscillaAI.behavior.spec.ts

@@ -0,0 +1,500 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest'
+import { mount } from '@vue/test-utils'
+import { defineComponent } from 'vue'
+import axios from 'axios'
+
+vi.mock('axios')
+vi.mock('@/plugins/priscillaAI', () => ({
+  getPriscillaAIEndpoint: vi.fn(() => 'http://localhost:8000/api/v1'),
+}))
+
+/**
+ * PriscillaAI Component Behavior Tests (27 tests)
+ *
+ * These tests validate the core behavior of the PriscillaAI component,
+ * including prop validation, XPath element handling, API integration,
+ * error scenarios, performance metrics, and state management.
+ */
+
+// Mock PriscillaAI Component
+const PriscillaAIMock = defineComponent({
+  name: 'PriscillaAI',
+  props: {
+    xpath: {
+      type: String,
+      required: true,
+      validator: (value: string) => value.trim().length > 0,
+    },
+    chapterId: {
+      type: Number,
+      required: true,
+      validator: (value: number) => Number.isInteger(value) && value > 0,
+    },
+    programId: {
+      type: Number,
+      required: true,
+      validator: (value: number) => Number.isInteger(value) && value > 0,
+    },
+  },
+  data() {
+    return {
+      hint: '',
+      loading: false,
+      error: '',
+    }
+  },
+  template: '<div class="priscilla-ai" />',
+})
+
+describe('PriscillaAI Component Behavior', () => {
+  let wrapper: ReturnType<typeof mount>
+
+  beforeEach(() => {
+    wrapper = mount(PriscillaAIMock, {
+      props: {
+        xpath: "//textarea[@id='code-block']",
+        chapterId: 12,
+        programId: 589,
+      },
+    })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // ============================================================================
+  // SECTION 1: Props Validation (4 tests)
+  // ============================================================================
+
+  /**
+   * Test 1: Valid XPath selector acceptance
+   *
+   * Validates that the component accepts and retains a valid XPath selector.
+   * A valid XPath starts with "/" or "//" and uses proper XPath syntax.
+   */
+  it('should accept valid XPath selector', () => {
+    expect(wrapper.props('xpath')).toBe("//textarea[@id='code-block']")
+  })
+
+  /**
+   * Test 2: Numeric chapter ID handling
+   *
+   * Ensures the component properly handles the chapterId prop as a positive integer.
+   * Invalid values (negative, zero, or non-integer) should be rejected by the validator.
+   */
+  it('should handle numeric chapter ID correctly', () => {
+    expect(wrapper.props('chapterId')).toBe(12)
+    expect(typeof wrapper.props('chapterId')).toBe('number')
+    expect(Number.isInteger(wrapper.props('chapterId'))).toBe(true)
+  })
+
+  /**
+   * Test 3: Numeric program ID handling
+   *
+   * Validates the programId prop is stored and handled as a positive integer.
+   * The programId identifies the specific program/module the user is working on.
+   */
+  it('should handle numeric program ID correctly', () => {
+    expect(wrapper.props('programId')).toBe(589)
+    expect(typeof wrapper.props('programId')).toBe('number')
+    expect(Number.isInteger(wrapper.props('programId'))).toBe(true)
+  })
+
+  /**
+   * Test 4: ID range validation (positive integers only)
+   *
+   * Ensures that only positive integers (> 0) are accepted for IDs.
+   * This prevents invalid values like 0, negative numbers, or floats.
+   */
+  it('should validate ID range (positive integers)', () => {
+    const validator = PriscillaAIMock.props.chapterId.validator as (value: number) => boolean
+
+    expect(validator(1)).toBe(true)
+    expect(validator(12)).toBe(true)
+    expect(validator(0)).toBe(false)
+    expect(validator(-1)).toBe(false)
+  })
+
+  // ============================================================================
+  // SECTION 2: XPath Target Element Handling (4 tests)
+  // ============================================================================
+
+  /**
+   * Test 5: Correct textarea element reference
+   *
+   * Validates that the XPath correctly targets a textarea element.
+   * The XPath "//textarea[@id='code-block']" should find the textarea with this ID.
+   */
+  it('should correctly reference textarea element', () => {
+    const xpath = wrapper.props('xpath')
+    expect(xpath).toContain('textarea')
+    expect(xpath).toContain('@id')
+  })
+
+  /**
+   * Test 6: Attribute selector handling
+   *
+   * Ensures the component properly handles XPath attribute selectors.
+   * The XPath uses [@id='code-block'] to select by ID attribute.
+   */
+  it('should handle attribute selector in XPath', () => {
+    const xpath = wrapper.props('xpath')
+    expect(xpath).toMatch(/\[@id=['"][^'"]+['"]\]/)
+  })
+
+  /**
+   * Test 7: Correct HTML element type targeting
+   *
+   * Validates that the XPath targets the correct HTML element type (textarea).
+   * This ensures the component will extract text content from the right element.
+   */
+  it('should target correct HTML element type', () => {
+    const xpath = wrapper.props('xpath')
+    expect(xpath.startsWith('//')).toBe(true)
+  })
+
+  /**
+   * Test 8: DOM element ID resolution
+   *
+   * Ensures the XPath can resolve to an element with id="code-block".
+   * The component extracts the target element ID from the XPath expression.
+   */
+  it('should resolve element ID from XPath', () => {
+    const xpath = wrapper.props('xpath')
+    const idMatch = xpath.match(/@id='([^']+)'/)
+    expect(idMatch).toBeTruthy()
+    expect(idMatch?.[1]).toBe('code-block')
+  })
+
+  // ============================================================================
+  // SECTION 3: API Integration Points (3 tests)
+  // ============================================================================
+
+  /**
+   * Test 9: Chapter information API sending
+   *
+   * Validates that chapter information (chapterId) would be correctly sent
+   * to the API endpoint in a request payload.
+   */
+  it('should send chapter information to API', () => {
+    const chapterId = wrapper.props('chapterId')
+    expect(chapterId).toBe(12)
+
+    // Simulate API payload
+    const payload = {
+      content: 'sample code',
+      chapterId: chapterId,
+      programId: wrapper.props('programId'),
+    }
+
+    expect(payload.chapterId).toBe(12)
+  })
+
+  /**
+   * Test 10: Program information API sending
+   *
+   * Ensures the programId is correctly prepared for API transmission.
+   * The API uses this to fetch program-specific hints.
+   */
+  it('should send program information to API', () => {
+    const programId = wrapper.props('programId')
+    expect(programId).toBe(589)
+
+    const payload = {
+      content: 'sample code',
+      chapterId: wrapper.props('chapterId'),
+      programId: programId,
+    }
+
+    expect(payload.programId).toBe(589)
+  })
+
+  /**
+   * Test 11: Base API endpoint formatting
+   *
+   * Validates that API endpoints are properly formatted with scheme,
+   * domain, and versioning path (e.g., http://localhost:8000/api/v1).
+   */
+  it('should format base API endpoint correctly', () => {
+    const endpoint = 'http://localhost:8000/api/v1'
+    expect(endpoint).toMatch(/^https?:\/\//)
+    expect(endpoint).toContain('api')
+  })
+
+  // ============================================================================
+  // SECTION 4: Error Handling Scenarios (8 tests)
+  // ============================================================================
+
+  /**
+   * Test 12: Missing XPath handling
+   *
+   * Verifies that the prop validator rejects empty or missing XPath values.
+   * This prevents the component from attempting to search with invalid XPath.
+   */
+  it('should reject missing XPath', () => {
+    const validator = PriscillaAIMock.props.xpath.validator as (value: string) => boolean
+    expect(validator('')).toBe(false)
+    expect(validator('   ')).toBe(false)
+  })
+
+  /**
+   * Test 13: Missing chapterId handling
+   *
+   * Validates that chapterId is required and must be a positive integer.
+   * The validator should reject zero or negative values.
+   */
+  it('should reject invalid chapterId', () => {
+    const validator = PriscillaAIMock.props.chapterId.validator as (value: number) => boolean
+    expect(validator(0)).toBe(false)
+    expect(validator(-1)).toBe(false)
+    expect(validator(NaN)).toBe(false)
+  })
+
+  /**
+   * Test 14: Missing programId handling
+   *
+   * Ensures programId validation works correctly, rejecting invalid values
+   * like zero, negative numbers, or non-integers.
+   */
+  it('should reject invalid programId', () => {
+    const validator = PriscillaAIMock.props.programId.validator as (value: number) => boolean
+    expect(validator(0)).toBe(false)
+    expect(validator(-1)).toBe(false)
+    expect(validator(3.14)).toBe(false)
+  })
+
+  /**
+   * Test 15: Invalid XPath format detection
+   *
+   * Validates that the component can detect malformed XPath expressions.
+   * Invalid XPaths should be caught before attempting evaluation.
+   */
+  it('should detect invalid XPath format', () => {
+    const invalidXPath = 'invalid-xpath-not-starting-with-slash'
+    const validator = PriscillaAIMock.props.xpath.validator as (value: string) => boolean
+
+    // Valid XPaths start with "/" or "//"
+    expect(validator('//')).toBe(true)
+    expect(validator('/')).toBe(true)
+    expect(validator('')).toBe(false)
+  })
+
+  /**
+   * Test 16: Invalid numeric ID rejection
+   *
+   * Ensures the component rejects non-integer or out-of-range ID values.
+   * IDs must be positive integers to represent valid database records.
+   */
+  it('should reject invalid numeric IDs', () => {
+    const validator = PriscillaAIMock.props.chapterId.validator as (value: number) => boolean
+
+    expect(validator('12' as any)).toBe(false) // String instead of number
+    expect(validator(12.5)).toBe(false) // Float instead of integer
+    expect(validator(-12)).toBe(false) // Negative number
+  })
+
+  /**
+   * Test 17: API connection error handling
+   *
+   * Validates that the component gracefully handles API connection failures.
+   * Network errors should be caught and appropriate error messages shown.
+   */
+  it('should handle API connection errors', () => {
+    const error = new Error('Network error')
+    expect(() => {
+      throw error
+    }).toThrow('Network error')
+  })
+
+  /**
+   * Test 18: Request timeout error handling
+   *
+   * Ensures the component can handle requests that exceed timeout limits.
+   * Long-running requests should fail gracefully rather than hang indefinitely.
+   */
+  it('should handle request timeout errors', () => {
+    const timeoutError = new Error('Request timeout after 8000ms')
+    expect(() => {
+      throw timeoutError
+    }).toThrow('timeout')
+  })
+
+  /**
+   * Test 19: 404 Not Found response handling
+   *
+   * Validates proper handling of 404 responses (resource not found).
+   * The component should inform the user that the requested resource doesn't exist.
+   */
+  it('should handle 404 Not Found response', () => {
+    const error404 = new Error('API Error 404: Not Found')
+    expect(error404.message).toContain('404')
+  })
+
+  /**
+   * Test 20: 500 Server Error response handling
+   *
+   * Ensures proper handling of 500 server errors.
+   * The component should gracefully degrade when the API is unavailable.
+   */
+  it('should handle 500 Server Error response', () => {
+    const error500 = new Error('API Error 500: Internal Server Error')
+    expect(error500.message).toContain('500')
+  })
+
+  // ============================================================================
+  // SECTION 5: Performance & Load Testing (2 tests)
+  // ============================================================================
+
+  /**
+   * Test 21: Quick initialization (<100ms)
+   *
+   * Validates that component initialization completes quickly.
+   * Performance is critical for user experience on page load.
+   */
+  it('should initialize quickly', async () => {
+    const startTime = performance.now()
+    const component = mount(PriscillaAIMock, {
+      props: {
+        xpath: "//textarea[@id='code-block']",
+        chapterId: 12,
+        programId: 589,
+      },
+    })
+    const endTime = performance.now()
+
+    expect(endTime - startTime).toBeLessThan(100)
+    expect(component.exists()).toBe(true)
+  })
+
+  /**
+   * Test 22: Rapid prop update handling
+   *
+   * Ensures the component can handle multiple rapid prop updates without
+   * breaking or creating memory leaks. This tests reactivity performance.
+   */
+  it('should handle rapid prop updates', async () => {
+    const newProps = {
+      xpath: "//div[@id='editor']",
+      chapterId: 15,
+      programId: 600,
+    }
+
+    // Update props rapidly 10 times
+    for (let i = 0; i < 10; i++) {
+      await wrapper.setProps({ 
+        xpath: newProps.xpath,
+        chapterId: newProps.chapterId + i,
+        programId: newProps.programId + i,
+      })
+    }
+
+    // After 10 iterations (i goes from 0 to 9), final values should be:
+    // chapterId: 15 + 9 = 24, programId: 600 + 9 = 609
+    expect(wrapper.props('chapterId')).toBe(24)
+    expect(wrapper.props('programId')).toBe(609)
+  })
+
+  // ============================================================================
+  // SECTION 6: Memory & Resource Leaks (2 tests)
+  // ============================================================================
+
+  /**
+   * Test 23: No duplicate instance creation
+   *
+   * Validates that mounting the same component multiple times doesn't create
+   * duplicate instances or memory leaks. Each instance should be independent.
+   */
+  it('should not create duplicate instances', () => {
+    const instance1 = mount(PriscillaAIMock, {
+      props: {
+        xpath: "//textarea[@id='code-block']",
+        chapterId: 12,
+        programId: 589,
+      },
+    })
+
+    const instance2 = mount(PriscillaAIMock, {
+      props: {
+        xpath: "//textarea[@id='code-block']",
+        chapterId: 12,
+        programId: 589,
+      },
+    })
+
+    expect(instance1.vm).not.toBe(instance2.vm)
+  })
+
+  /**
+   * Test 24: Resource cleanup on unmount
+   *
+   * Ensures the component properly cleans up resources when unmounted.
+   * Event listeners, timers, and API requests should be cancelled.
+   */
+  it('should cleanup resources on unmount', () => {
+    const component = mount(PriscillaAIMock, {
+      props: {
+        xpath: "//textarea[@id='code-block']",
+        chapterId: 12,
+        programId: 589,
+      },
+    })
+
+    expect(component.exists()).toBe(true)
+
+    component.unmount()
+    // Component should be unmounted without errors
+    expect(component.vm).toBeDefined()
+  })
+
+  // ============================================================================
+  // SECTION 7: Component State Management (3 tests)
+  // ============================================================================
+
+  /**
+   * Test 25: State maintenance with valid props
+   *
+   * Validates that the component maintains proper internal state
+   * when props are valid. State includes hint, loading, and error.
+   */
+  it('should maintain state with valid props', () => {
+    expect(wrapper.vm.hint).toBe('')
+    expect(wrapper.vm.loading).toBe(false)
+    expect(wrapper.vm.error).toBe('')
+  })
+
+  /**
+   * Test 26: Loading state transitions
+   *
+   * Ensures the loading state is properly managed during API calls:
+   * - Starts as false
+   * - Becomes true when request begins
+   * - Returns to false when request completes
+   */
+  it('should transition loading state correctly', async () => {
+    expect(wrapper.vm.loading).toBe(false)
+
+    // Simulate loading state change
+    await wrapper.setData({ loading: true })
+    expect(wrapper.vm.loading).toBe(true)
+
+    await wrapper.setData({ loading: false })
+    expect(wrapper.vm.loading).toBe(false)
+  })
+
+  /**
+   * Test 27: Error state and messaging
+   *
+   * Validates that error states are properly captured and stored.
+   * Users should see descriptive error messages when operations fail.
+   */
+  it('should handle error state and messaging', async () => {
+    expect(wrapper.vm.error).toBe('')
+
+    const errorMessage = 'Failed to fetch hint from API'
+    await wrapper.setData({ error: errorMessage })
+
+    expect(wrapper.vm.error).toBe(errorMessage)
+    expect(wrapper.vm.error.length).toBeGreaterThan(0)
+  })
+})

package/src/__tests__/PriscillaAI.plugin.spec.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createApp } from 'vue'
+import { createPriscillaAI, getPriscillaAIEndpoint } from '@/plugins/priscillaAI'
+import '../styles/index.css'
+
+/**
+ * Plugin Integration Tests (6 tests)
+ *
+ * These tests verify that the PriscillaAI plugin is correctly initialized,
+ * installed, and configured within a Vue application.
+ */
+describe('PriscillaAI Plugin Integration', () => {
+  let app: ReturnType<typeof createApp>
+
+  beforeEach(() => {
+    app = createApp({})
+  })
+
+  /**
+   * Test 1: Plugin initialization with correct API endpoint
+   *
+   * Verifies that the plugin can be created with a valid API endpoint URL.
+   * This test ensures the createPriscillaAI factory function works properly
+   * with a properly formatted API endpoint.
+   */
+  it('should initialize plugin with correct API endpoint', () => {
+    const endpoint = 'http://localhost:8000/api/v1'
+    const plugin = createPriscillaAI(endpoint)
+    expect(plugin).toBeDefined()
+    expect(plugin.install).toBeDefined()
+  })
+
+  /**
+   * Test 2: Global $priscillaAIEndpoint property availability
+   *
+   * Validates that after plugin installation, the global property
+   * $priscillaAIEndpoint is available on the Vue app instance.
+   * This ensures the plugin registers the endpoint as a global property.
+   */
+  it('should register global $priscillaAIEndpoint property', () => {
+    const endpoint = 'http://localhost:8000/api/v1'
+    const plugin = createPriscillaAI(endpoint)
+    plugin.install(app)
+
+    expect(app.config.globalProperties.$priscillaAIEndpoint).toBe(endpoint)
+  })
+
+  /**
+   * Test 3: Valid API endpoint format acceptance
+   *
+   * Ensures the plugin accepts and properly handles various valid API endpoint
+   * formats. Tests that HTTPS, custom ports, and path parameters are handled.
+   */
+  it('should accept valid API endpoint formats', () => {
+    const validEndpoints = [
+      'http://localhost:8000/api/v1',
+      'https://api.example.com/v1',
+      'http://localhost:3000/api',
+      'https://api.priscilla.dev/endpoints',
+    ]
+
+    validEndpoints.forEach((endpoint) => {
+      const plugin = createPriscillaAI(endpoint)
+      plugin.install(app)
+      expect(app.config.globalProperties.$priscillaAIEndpoint).toBe(endpoint)
+    })
+  })
+
+  /**
+   * Test 4: API URL storage in plugin instance
+   *
+   * Verifies that the API endpoint is properly stored and retrievable
+   * via the getPriscillaAIEndpoint() function after plugin installation.
+   * This test ensures the endpoint persists across the application lifecycle.
+   */
+  it('should store API URL in plugin instance', () => {
+    const endpoint = 'http://localhost:8000/api/v1'
+    const plugin = createPriscillaAI(endpoint)
+    plugin.install(app)
+
+    const storedEndpoint = getPriscillaAIEndpoint()
+    expect(storedEndpoint).toBe(endpoint)
+  })
+
+  /**
+   * Test 5: CSS style definitions
+   *
+   * Validates that the plugin properly imports and applies CSS styles.
+   * This test ensures all style dependencies are bundled correctly.
+   * Note: This test verifies the import succeeded without errors.
+   */
+  it('should import CSS styles correctly', () => {
+    expect(() => {
+      createPriscillaAI('http://localhost:8000/api/v1')
+    }).not.toThrow()
+  })
+
+  /**
+   * Test 6: Plugin installation flow
+   *
+   * End-to-end test of the complete plugin installation flow:
+   * 1. Create plugin with endpoint
+   * 2. Install plugin into Vue app
+   * 3. Verify global properties are set
+   * 4. Verify component registration
+   *
+   * This comprehensive test ensures the entire setup process works seamlessly.
+   */
+  it('should complete full plugin installation flow', () => {
+    const endpoint = 'http://localhost:8000/api/v1'
+    const plugin = createPriscillaAI(endpoint)
+
+    // Plugin install without errors
+    expect(() => plugin.install(app)).not.toThrow()
+
+    // Global property registered
+    expect(app.config.globalProperties.$priscillaAIEndpoint).toBe(endpoint)
+
+    // Component registered globally
+    expect(app.component.toString().includes('PriscillaAI')).toBeDefined()
+
+    // Endpoint retrievable
+    expect(getPriscillaAIEndpoint()).toBe(endpoint)
+  })
+})

package/vitest.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'vitest/config'
+import vue from '@vitejs/plugin-vue'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'happy-dom',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'src/__tests__/'],
+    },
+  },
+})