@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/generating-lwc-components/assets/jest-test/componentName.test.js.example

@@ -0,0 +1,371 @@
+/**
+ * JEST TEST TEMPLATE FOR LWC
+ *
+ * This template demonstrates Jest testing patterns for LWC:
+ * - Component rendering
+ * - Wire service mocking
+ * - Apex method mocking
+ * - Event handling
+ * - DOM queries
+ * - Async testing
+ *
+ * This file ships with a .example suffix so Jest does not auto-discover it
+ * inside installed skill folders. Copy it into your project and rename it to:
+ * force-app/main/default/lwc/<yourComponent>/__tests__/<yourComponent>.test.js
+ *
+ * Replace: componentName → yourComponentName
+ * Replace: ComponentName → YourComponentName
+ */
+
+import { createElement } from 'lwc';
+import ComponentName from 'c/componentName';
+
+// Mock Apex methods
+import getRecords from '@salesforce/apex/ComponentController.getRecords';
+import saveRecord from '@salesforce/apex/ComponentController.saveRecord';
+
+// Mock wire adapters
+import { getRecord } from 'lightning/uiRecordApi';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MOCK SETUP
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Mock Apex methods
+jest.mock(
+    '@salesforce/apex/ComponentController.getRecords',
+    () => ({ default: jest.fn() }),
+    { virtual: true }
+);
+
+jest.mock(
+    '@salesforce/apex/ComponentController.saveRecord',
+    () => ({ default: jest.fn() }),
+    { virtual: true }
+);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TEST DATA
+// ═══════════════════════════════════════════════════════════════════════════
+
+const MOCK_RECORDS = [
+    { Id: '001xx000003DGFAAA4', Name: 'Test Account 1', Industry: 'Technology' },
+    { Id: '001xx000003DGFBBB4', Name: 'Test Account 2', Industry: 'Finance' },
+    { Id: '001xx000003DGFCCC4', Name: 'Test Account 3', Industry: 'Healthcare' }
+];
+
+const MOCK_RECORD = {
+    Id: '001xx000003DGFAAA4',
+    Name: { value: 'Test Account' },
+    Industry: { value: 'Technology' },
+    Phone: { value: '555-1234' }
+};
+
+const MOCK_ERROR = {
+    body: { message: 'An error occurred' },
+    ok: false,
+    status: 500,
+    statusText: 'Internal Server Error'
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Flush all pending promises in the event queue
+ */
+const flushPromises = () => new Promise(resolve => setTimeout(resolve, 0));
+
+/**
+ * Create component with optional public properties
+ */
+function createComponent(props = {}) {
+    const element = createElement('c-component-name', { is: ComponentName });
+
+    // Set public properties
+    Object.keys(props).forEach(key => {
+        element[key] = props[key];
+    });
+
+    document.body.appendChild(element);
+    return element;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TEST SUITE
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('c-component-name', () => {
+    // Reset DOM and mocks after each test
+    afterEach(() => {
+        // Remove all created elements
+        while (document.body.firstChild) {
+            document.body.removeChild(document.body.firstChild);
+        }
+        // Reset all mocks
+        jest.clearAllMocks();
+    });
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // RENDERING TESTS
+    // ═══════════════════════════════════════════════════════════════════════
+
+    describe('rendering', () => {
+        it('renders component with default state', () => {
+            const element = createComponent();
+
+            // Check component is rendered
+            const card = element.shadowRoot.querySelector('lightning-card');
+            expect(card).not.toBeNull();
+        });
+
+        it('renders with custom title property', () => {
+            const element = createComponent({ title: 'Custom Title' });
+
+            const card = element.shadowRoot.querySelector('lightning-card');
+            expect(card.title).toBe('Custom Title');
+        });
+
+        it('displays loading spinner initially', () => {
+            const element = createComponent();
+
+            const spinner = element.shadowRoot.querySelector('lightning-spinner');
+            expect(spinner).not.toBeNull();
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // DATA FETCHING TESTS
+    // ═══════════════════════════════════════════════════════════════════════
+
+    describe('data fetching', () => {
+        it('displays records when data is returned', async () => {
+            // Setup mock response
+            getRecords.mockResolvedValue(MOCK_RECORDS);
+
+            const element = createComponent({ recordId: '001xx000000000' });
+
+            // Wait for async operations
+            await flushPromises();
+
+            // Check records are displayed
+            const items = element.shadowRoot.querySelectorAll('.record-item');
+            expect(items.length).toBe(3);
+        });
+
+        it('displays error message when fetch fails', async () => {
+            // Setup mock error
+            getRecords.mockRejectedValue(MOCK_ERROR);
+
+            const element = createComponent({ recordId: '001xx000000000' });
+
+            await flushPromises();
+
+            // Check error is displayed
+            const error = element.shadowRoot.querySelector('.error-message');
+            expect(error).not.toBeNull();
+            expect(error.textContent).toContain('An error occurred');
+        });
+
+        it('displays empty state when no records returned', async () => {
+            getRecords.mockResolvedValue([]);
+
+            const element = createComponent({ recordId: '001xx000000000' });
+
+            await flushPromises();
+
+            const emptyState = element.shadowRoot.querySelector('.empty-state');
+            expect(emptyState).not.toBeNull();
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // WIRE SERVICE TESTS
+    // ═══════════════════════════════════════════════════════════════════════
+
+    describe('wire service', () => {
+        it('fetches record data via wire adapter', async () => {
+            const element = createComponent({ recordId: '001xx000000000' });
+
+            // Emit wire data
+            getRecord.emit(MOCK_RECORD);
+
+            await flushPromises();
+
+            // Verify data is displayed
+            const nameField = element.shadowRoot.querySelector('.account-name');
+            expect(nameField.textContent).toBe('Test Account');
+        });
+
+        it('handles wire adapter error', async () => {
+            const element = createComponent({ recordId: '001xx000000000' });
+
+            // Emit error
+            getRecord.error(MOCK_ERROR);
+
+            await flushPromises();
+
+            const error = element.shadowRoot.querySelector('.error-message');
+            expect(error).not.toBeNull();
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // EVENT HANDLING TESTS
+    // ═══════════════════════════════════════════════════════════════════════
+
+    describe('event handling', () => {
+        it('dispatches recordselected event on row click', async () => {
+            getRecords.mockResolvedValue(MOCK_RECORDS);
+
+            const element = createComponent({ recordId: '001xx000000000' });
+            await flushPromises();
+
+            // Create event handler mock
+            const handler = jest.fn();
+            element.addEventListener('recordselected', handler);
+
+            // Click on first record
+            const firstRow = element.shadowRoot.querySelector('.record-item');
+            firstRow.click();
+
+            // Verify event was dispatched
+            expect(handler).toHaveBeenCalled();
+            expect(handler.mock.calls[0][0].detail).toEqual({
+                recordId: '001xx000003DGFAAA4',
+                recordName: 'Test Account 1'
+            });
+        });
+
+        it('handles refresh button click', async () => {
+            getRecords.mockResolvedValue(MOCK_RECORDS);
+
+            const element = createComponent({ recordId: '001xx000000000' });
+            await flushPromises();
+
+            // Clear mock to track new calls
+            getRecords.mockClear();
+
+            // Click refresh
+            const refreshButton = element.shadowRoot.querySelector('lightning-button-icon[icon-name="utility:refresh"]');
+            refreshButton.click();
+
+            await flushPromises();
+
+            // Verify data was re-fetched
+            expect(getRecords).toHaveBeenCalled();
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // FORM SUBMISSION TESTS
+    // ═══════════════════════════════════════════════════════════════════════
+
+    describe('form submission', () => {
+        it('saves record successfully', async () => {
+            saveRecord.mockResolvedValue({ Id: '001xx000000NEW', Name: 'New Account' });
+
+            const element = createComponent();
+            await flushPromises();
+
+            // Fill form fields
+            const nameInput = element.shadowRoot.querySelector('lightning-input[name="Name"]');
+            nameInput.value = 'New Account';
+            nameInput.dispatchEvent(new CustomEvent('change'));
+
+            // Submit form
+            const submitButton = element.shadowRoot.querySelector('lightning-button[type="submit"]');
+            submitButton.click();
+
+            await flushPromises();
+
+            // Verify save was called
+            expect(saveRecord).toHaveBeenCalledWith({
+                record: expect.objectContaining({ Name: 'New Account' })
+            });
+        });
+
+        it('displays validation error for required fields', async () => {
+            const element = createComponent();
+            await flushPromises();
+
+            // Submit without filling required fields
+            const submitButton = element.shadowRoot.querySelector('lightning-button[type="submit"]');
+            submitButton.click();
+
+            await flushPromises();
+
+            // Check validation message
+            const input = element.shadowRoot.querySelector('lightning-input[required]');
+            expect(input.reportValidity).toHaveBeenCalled;
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ACCESSIBILITY TESTS
+    // ═══════════════════════════════════════════════════════════════════════
+
+    describe('accessibility', () => {
+        it('has accessible button labels', async () => {
+            const element = createComponent();
+            await flushPromises();
+
+            const buttons = element.shadowRoot.querySelectorAll('lightning-button, lightning-button-icon');
+            buttons.forEach(button => {
+                // Each button should have label or alternative-text
+                const hasLabel = button.label || button.alternativeText;
+                expect(hasLabel).toBeTruthy();
+            });
+        });
+
+        it('announces loading state to screen readers', async () => {
+            const element = createComponent();
+
+            const spinner = element.shadowRoot.querySelector('lightning-spinner');
+            expect(spinner.alternativeText).toBe('Loading');
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // EDGE CASES
+    // ═══════════════════════════════════════════════════════════════════════
+
+    describe('edge cases', () => {
+        it('handles null recordId gracefully', async () => {
+            const element = createComponent({ recordId: null });
+            await flushPromises();
+
+            // Should not crash
+            expect(element).toBeTruthy();
+        });
+
+        it('handles special characters in data', async () => {
+            const specialRecords = [
+                { Id: '001xx000000001', Name: "Test's <Account> & \"Quotes\"" }
+            ];
+            getRecords.mockResolvedValue(specialRecords);
+
+            const element = createComponent({ recordId: '001xx000000000' });
+            await flushPromises();
+
+            const name = element.shadowRoot.querySelector('.record-name');
+            expect(name.textContent).toContain("Test's <Account>");
+        });
+
+        it('handles rapid successive updates', async () => {
+            const element = createComponent();
+            await flushPromises();
+
+            // Simulate rapid changes
+            for (let i = 0; i < 10; i++) {
+                element.recordId = `001xx00000000${i}`;
+            }
+
+            await flushPromises();
+
+            // Component should still be stable
+            expect(element.shadowRoot.querySelector('lightning-card')).not.toBeNull();
+        });
+    });
+});

package/skills/generating-lwc-components/assets/message-channel/RecordSelected.messageChannel-meta.xml

@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    LIGHTNING MESSAGE CHANNEL TEMPLATE
+
+    Message channels enable communication between LWC components
+    that don't have a parent-child relationship (cross-DOM communication).
+
+    Use cases:
+    - Components on different parts of the page
+    - LWC to Aura communication
+    - LWC to Visualforce communication
+
+    Replace: RecordSelected → YourChannelName
+-->
+<LightningMessageChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!-- Human-readable label shown in Setup -->
+    <masterLabel>Record Selected</masterLabel>
+
+    <!-- Description for documentation -->
+    <description>
+        Message channel for communicating record selection events between
+        components across the page. Used when a user selects a record in
+        one component and other components need to react.
+    </description>
+
+    <!-- Expose to Lightning web components -->
+    <isExposed>true</isExposed>
+
+    <!--
+        Message payload fields.
+        Define all data that can be sent through the channel.
+    -->
+    <lightningMessageFields>
+        <!-- Record ID field -->
+        <fieldName>recordId</fieldName>
+        <description>The Id of the selected record</description>
+    </lightningMessageFields>
+
+    <lightningMessageFields>
+        <!-- Record Name field -->
+        <fieldName>recordName</fieldName>
+        <description>The name of the selected record</description>
+    </lightningMessageFields>
+
+    <lightningMessageFields>
+        <!-- Object API Name field -->
+        <fieldName>objectApiName</fieldName>
+        <description>The API name of the object (e.g., Account, Contact)</description>
+    </lightningMessageFields>
+
+    <lightningMessageFields>
+        <!-- Source Component field -->
+        <fieldName>sourceComponent</fieldName>
+        <description>The name of the component that published this message</description>
+    </lightningMessageFields>
+
+    <lightningMessageFields>
+        <!-- Timestamp field -->
+        <fieldName>timestamp</fieldName>
+        <description>When the selection occurred (ISO 8601 format)</description>
+    </lightningMessageFields>
+
+    <!--
+        Additional fields for complex payloads.
+        Use JSON strings for nested data.
+    -->
+    <lightningMessageFields>
+        <fieldName>payload</fieldName>
+        <description>Additional data as JSON string for complex scenarios</description>
+    </lightningMessageFields>
+</LightningMessageChannel>

package/skills/generating-lwc-components/assets/message-channel/lmsPublisher.js

@@ -0,0 +1,103 @@
+/**
+ * LIGHTNING MESSAGE SERVICE - PUBLISHER TEMPLATE
+ *
+ * This component demonstrates publishing messages via LMS.
+ * Use LMS when components need to communicate but:
+ * - Don't have a parent-child relationship
+ * - Are in different parts of the page
+ * - Need to communicate between LWC, Aura, and Visualforce
+ *
+ * Replace: lmsPublisher → yourComponentName
+ */
+
+import { LightningElement, wire } from 'lwc';
+import { publish, MessageContext } from 'lightning/messageService';
+import RECORD_SELECTED_CHANNEL from '@salesforce/messageChannel/RecordSelected__c';
+
+export default class LmsPublisher extends LightningElement {
+    // ═══════════════════════════════════════════════════════════════════════
+    // MESSAGE CONTEXT
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * MessageContext provides the scope for publishing/subscribing.
+     * Wire it to get the current context automatically.
+     */
+    @wire(MessageContext)
+    messageContext;
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // PUBLISH METHODS
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * Publish a simple message with record selection
+     */
+    handleRecordSelect(event) {
+        const recordId = event.target.dataset.id;
+        const recordName = event.target.dataset.name;
+
+        // Create message payload
+        const payload = {
+            recordId: recordId,
+            recordName: recordName,
+            objectApiName: 'Account',
+            sourceComponent: 'lmsPublisher',
+            timestamp: new Date().toISOString()
+        };
+
+        // Publish to the message channel
+        publish(this.messageContext, RECORD_SELECTED_CHANNEL, payload);
+
+        console.log('Published message:', payload);
+    }
+
+    /**
+     * Publish with complex payload (JSON string for nested data)
+     */
+    publishWithComplexPayload(recordData) {
+        const payload = {
+            recordId: recordData.Id,
+            recordName: recordData.Name,
+            objectApiName: 'Account',
+            sourceComponent: 'lmsPublisher',
+            timestamp: new Date().toISOString(),
+            payload: JSON.stringify({
+                additionalField1: recordData.field1,
+                additionalField2: recordData.field2,
+                nestedObject: {
+                    key1: 'value1',
+                    key2: 'value2'
+                }
+            })
+        };
+
+        publish(this.messageContext, RECORD_SELECTED_CHANNEL, payload);
+    }
+
+    /**
+     * Publish from imperative action (e.g., after Apex call)
+     */
+    async handleSaveAndPublish() {
+        try {
+            // Perform some action
+            const result = await this.saveRecord();
+
+            // Publish result to other components
+            publish(this.messageContext, RECORD_SELECTED_CHANNEL, {
+                recordId: result.Id,
+                recordName: result.Name,
+                objectApiName: 'Account',
+                sourceComponent: 'lmsPublisher',
+                timestamp: new Date().toISOString()
+            });
+        } catch (error) {
+            console.error('Save failed:', error);
+        }
+    }
+
+    // Placeholder for actual save logic
+    async saveRecord() {
+        return { Id: '001xx000000000', Name: 'Test Account' };
+    }
+}