@c8y/websdk 1023.81.2 → 1023.82.0

package/dist/templates/ai-configs/windsurf/rules/e2e-tests.instructions.md

@@ -0,0 +1,187 @@
+---
+name: "Cypress E2E & Component Testing Guide"
+description: "Instructions for Cypress end-to-end and component tests in Cumulocity applications"
+applyTo: "**/*.cy.ts"
+paths: ["**/*.cy.ts"]
+---
+
+# Cypress Testing Guide
+
+## Test Types and Locations
+
+- **E2E tests** — `cypress/e2e/` — run against a real or intercepted Cumulocity tenant
+- **Component tests** — `cypress/component/` — mount Angular components in isolation via `cy.mount()`
+- **Fixtures** — `cypress/fixtures/` — mocked BE responses for component tests
+- **Support** — `cypress/support/` — custom commands (`cy.login()`, `cy.createDevice()`, etc.) and global configuration; auto-imported before every test
+- **Snapshots** — `cypress/snapshots/` — baseline, actual, and diff images for visual regression tests (see Visual Testing)
+
+## E2E Tests
+
+### Authentication and navigation
+
+```typescript
+beforeEach(() => {
+  cy.login(Cypress.env('username'), Cypress.env('password'));
+});
+
+cy.visit('/apps/cockpit/index.html#/group/123');
+```
+
+Always use `Cypress.env('username')` / `Cypress.env('password')` — never hardcode credentials.
+
+### API interception
+
+```typescript
+cy.intercept('GET', '/inventory/managedObjects/123', mockedObject).as('getMO');
+cy.wait('@getMO');
+
+// Query-parameter matching
+cy.intercept(
+  { pathname: '/inventory/managedObjects', query: { pageSize: '5' } },
+  { managedObjects: [] }
+);
+```
+
+Use `cy.intercept()` to stub slow or unpredictable backend calls; never use fixed `cy.wait(number)`.
+
+### Creating and cleaning up test data
+
+Use `cy.request()` for setup. Always clean up in `afterEach`:
+
+```typescript
+afterEach(() => {
+  createdIds.forEach(id => {
+    cy.request({ 
+      url: `/inventory/managedObjects/${id}?cascade=true`, 
+      method: 'DELETE', 
+      failOnStatusCode: false 
+    });
+  });
+});
+```
+
+Use `Cypress._.now()` to generate unique names: `e2eDevice${Cypress._.now()}`.
+
+## Component Tests
+
+### Mounting
+
+```typescript
+cy.mount(MyComponent, {
+  imports: [CoreModule.forRoot(), CommonModule, ...],
+  providers: [
+    { provide: MyService, useValue: stubService }
+  ],
+  componentProperties: { myInput: value }
+});
+```
+
+All components should be standalone — import them directly, no NgModule wrapping needed.
+
+### Mocked backend with fixtures
+
+Component tests that need BE responses can use recorded fixtures:
+
+```typescript
+it('should load data', () => {
+  cy.intercept('GET', '/inventory/managedObjects/*', { 
+    fixture: 'device.json' 
+  }).as('getDevice');
+  
+  cy.mount(MyComponent, { ... });
+  cy.wait('@getDevice');
+  cy.get('[data-cy="result"]').should('be.visible');
+});
+```
+
+Store fixture files in `cypress/fixtures/`.
+
+## Selectors
+
+Prefer `data-cy` attributes, then role/title attributes. Avoid CSS class selectors unless the class is part of the component's public contract (e.g. icon class names from the design system).
+
+Use consistent `data-cy` selectors with pattern: `<component-selector>--<element>-<details>`
+
+- Double hyphens (`--`) separate component selector from element
+- Single hyphens connect element type with descriptive details
+- Don't hesitate to use longer names for precision
+
+**Example:**
+```html
+<!-- In component template -->
+<button data-cy="c8y-custom-element-example--reset-button">Reset</button>
+<button data-cy="c8y-custom-element-example--submit">Submit</button>
+```
+
+**Usage:**
+```typescript
+cy.get('[data-cy="c8y-custom-element-example--reset-button"]').click();         // preferred
+cy.get('[title="Save"]').should('be.visible');        // acceptable for titled elements
+cy.get('c8y-ui-empty-state').should('be.visible');   // OK for component element selectors
+cy.get('.my-layout-class').should(...)               // avoid unless class is stable/intentional
+```
+
+## Assertions
+
+```typescript
+.should('be.visible')
+.should('contain.text', 'expected')
+.should('have.attr', 'href', '#/group/123')
+.should('not.exist')
+.should('be.disabled')
+.should('be.enabled')
+```
+
+Use `.should()` for all assertions (auto-retries). Avoid `.then()` for assertions.
+
+## Helper functions
+
+Extract repeated selection and assertion logic into named helper functions at the top of the spec or in a describe-level scope:
+
+```typescript
+function assertBreadcrumb(index: number, text: string) {
+  cy.get('[data-cy="breadcrumb-item"]').eq(index).should('contain.text', text);
+}
+```
+
+For component tests with multiple mounting configurations, create a named `mount*` function per variant.
+
+## Visual Testing
+
+```typescript
+cy.compareSnapshot('my-identifier'); // strict
+cy.compareSnapshot('my-identifier', 0.05); // with threshold
+```
+
+Run component tests in the dev container for snapshot consistency with CI:
+
+```bash
+yarn dc:up
+yarn dc:run:spec "cypress/component/path/to/spec.cy.ts"
+yarn dc:base:spec "cypress/component/path/to/spec.cy.ts"  # regenerate baseline
+```
+
+Snapshots: `cypress/snapshots/{base,actual,diff}/`
+
+To regenerate baseline snapshots, use your project's snapshot regeneration command or manually replace files in `cypress/snapshots/base/`.
+
+## Running Tests
+
+```bash
+# Open Cypress runner
+npx cypress open --config baseUrl=https://<tenant>.cumulocity.com --env username=<u>,password=<p>
+
+# Run headless
+npx cypress run --config baseUrl=https://<tenant>.cumulocity.com --e2e --env username=<u>,password=<p> --browser chrome
+
+# Filter by title substring (with cypress-grep plugin)
+npx cypress run --env grep=breadcrumb
+```
+
+## What NOT to Do
+
+- No `cy.wait(number)` — use `cy.wait('@alias')` or `.should()` retry
+- No hardcoded tenant IDs, credentials, or device IDs — use `Cypress.env()` (except cases related to e.g. password changes; make sure to document these exceptions clearly in the code and not use credentials of real users)
+- No `it.only` / `describe.only` / `context.only` committed to the repo
+- Use `cy.visit()` for navigation; add custom wait utilities if needed
+- Don't test trivial things just for coverage — test meaningful user-facing behavior

package/dist/templates/ai-configs/windsurf/rules/frontend.instructions.md

@@ -0,0 +1,251 @@
+---
+name: 'Frontend Development Guide'
+description: 'Instructions for Angular/TypeScript UI development'
+---
+
+## Persona
+
+You are a senior Angular developer working on a **Cumulocity IoT application**. You leverage the latest Angular features: signals, standalone components, and new control flow syntax. Performance and consistency are paramount.
+
+---
+
+## Resources
+
+- Angular docs: https://angular.dev/
+- Angular style guide: https://angular.dev/style-guide
+- Angular signals: https://angular.dev/guide/signals
+- Cumulocity Web SDK / Codex: https://cumulocity.com/codex/
+- Tutorial examples: https://github.com/Cumulocity-IoT/tutorial
+
+---
+
+## Before You Code
+
+1. **Check for existing patterns** — search the codebase for similar components or services before creating new ones. Check `@c8y/ngx-components` exports and [Codex](https://cumulocity.com/codex) (see main instructions for the full mandatory workflow).
+
+---
+
+## Critical Violations
+
+These are the highest-severity issues — NEVER introduce them:
+
+- **Unmanaged subscriptions** — every `.subscribe()` must have `takeUntilDestroyed()`, `takeUntil()`, or use `async` pipe
+- **Empty catch blocks** — propagate, display via `AlertService.danger()`, or comment why swallowed
+- **Committed secrets** — no API keys, tokens, passwords, or tenant-specific URLs in source
+- **Dynamic gettext()** — `gettext()` must receive a static string literal; dynamic strings break the entire translation pipeline
+
+---
+
+## Components
+
+- All new components must be **standalone** — do not set `standalone: true` explicitly (default since Angular 19+)
+- Set `changeDetection: ChangeDetectionStrategy.OnPush` in all `@Component` decorators
+- Keep components small — extract when template exceeds ~150 lines or class exceeds ~200 lines
+- Components focus on presentation; extract business logic, data mapping, and SDK calls to dedicated services
+- Use `readonly` for properties that should not change
+- Use `input()` instead of `@Input`, `output()` instead of `@Output`, `viewChild()` instead of `@ViewChild`
+- Do **not** use `@HostBinding` or `@HostListener` — use the `host` object in decorators
+- Use `NgOptimizedImage` for static images (does not work for inline base64)
+- Prefer Reactive forms over template-driven forms
+- Define model interfaces and constants in **dedicated files** (`models.ts`, `types.ts`), not inside component files
+- Keep JSDoc comments in sync with method signatures — out-of-sync documentation is worse than none
+- Use strict type checking where available per package
+- Split into `.ts`, `.html`, and `.scss` files. Use `c8y` prefix for component selectors
+
+### Example
+
+```ts
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+
+@Component({
+  selector: 'c8y-example-component',
+  templateUrl: './example.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class ExampleComponent {
+  protected readonly isServerRunning = signal(true);
+
+  toggleServerStatus() {
+    this.isServerRunning.update(v => !v);
+  }
+}
+```
+
+```html
+<section class="container">
+  @if (isServerRunning()) {
+  <span>{{ 'Yes, the server is running' | translate }}</span>
+  } @else {
+  <span>{{ 'No, the server is not running' | translate }}</span>
+  }
+  <button (click)="toggleServerStatus()">{{ 'Toggle Server Status' | translate }}</button>
+</section>
+```
+
+---
+
+## Templates
+
+- Use **native control flow** (`@if`, `@for`, `@switch`) — `*ngIf`, `*ngFor`, `*ngSwitch` are **forbidden**
+- Do **not** use `ngClass` or `ngStyle` — use `[class.x]` and `[style.x]` bindings
+- Do **not** import `CoreModule` in standalone components
+- Use `@let` to avoid repeating expressions
+- Use `async` pipe for observables in templates
+- `@for` track: use `item.id` or meaningful property; only `$index` for readonly primitives
+- Keep templates simple — no method calls in bindings (except pipes), no complex logic
+- Do not assume globals like `new Date()` are available in templates
+- Import pipes explicitly when used in a template
+- Use paths relative to the component `.ts` file for external templates/styles
+
+---
+
+## State Management & Subscriptions
+
+- **Signals** for local synchronous state; `computed()` for derived state
+- **RxJS/Promises** for async operations and API calls — don't mix paradigms in one use case
+- Do **not** use `mutate` on signals — use `update` or `set`
+- Do **not** run long-lived async (polling, intervals) in components — extract to services
+- Always unsubscribe: `takeUntilDestroyed()`, `takeUntil()`, or `async` pipe — never bare `.unsubscribe()` without `ngOnDestroy`
+
+---
+
+## Dependency Injection & Services
+
+- Use **one** DI pattern per file — don't mix constructor injection and `inject()` in the same file
+- `providedIn: 'root'` only for global singletons — scope to components/features when possible
+- Use `@c8y/client` for all Cumulocity REST calls — never `HttpClient` directly
+- Lazy-load feature routes and C8Y widget/plugin modules
+
+---
+
+## Styling
+
+- **Always use design tokens** — never hardcode colors (`#hex`, `rgb()`)
+  - `var(--brand-primary, var(--c8y-brand-primary))`
+  - Common tokens: `--c8y-brand-primary`, `--c8y-root-component-color-*`, `--c8y-root-component-background-*`, `--c8y-root-component-border-color`
+- Prefer Cumulocity utility classes over custom CSS
+- Avoid `::ng-deep` — use component encapsulation or design tokens
+- Don't use inline styles
+- Use SCSS for new files
+- Reference: https://cumulocity.com/codex/design-system/design-tokens/overview
+
+### Utility Class Quick Reference
+
+**Spacing:** `m-{side}-{amount}` / `p-{side}-{amount}` — sides: `t`, `r`, `b`, `l` or omit; amounts: 4, 8, 16, 24, 32, 40
+
+**Layout:** `d-flex` (row), `d-col` (column) | `j-c-{start|center|end|between|around|evenly}` | `a-i-{start|center|end|stretch}` | `gap-{4|8|16}`
+
+**Flex items:** `flex-grow`, `flex-no-shrink`, `flex-auto`, `fit-w`, `fit-h`, `min-width-0`, `min-height-0`
+
+**Width/height:** `max-width-100`, `min-width-100`, `max-height-inherit`
+
+**Position:** `p-relative`, `p-absolute`, `p-fixed`, `p-sticky`
+
+**Text:** `text-left`, `text-center`, `text-right`, `text-pre-wrap`, `text-break-word`, `text-truncate`, `text-truncate-wrap`
+
+**Display:** `d-flex`, `d-inline-flex`, `d-col`, `d-block`, `d-inline`, `d-inline-block`, `d-grid`, `d-contents`, `hidden`, `invisible`, `sr-only` | Responsive: `-xs`, `-sm`, `-md`, `-lg`
+
+**Icons:** `[c8yIcon]="'icon-name'"` | sizes: `icon-16`, `icon-20`, `icon-32` | decorative: `aria-hidden="true"`
+
+---
+
+## Internationalization
+
+- **Templates:** `{{ 'Text' | translate }}` for simple strings
+- **Templates (conditional):** prefer `@let label = 'Text' | translate;` for conditional or repeated translations. `gettext()` in templates is also valid if exposed as a component property and piped through `| translate`
+- **TypeScript:** `translateService.instant(gettext('Text'))` — `gettext()` marks for extraction only
+- **Placeholders:** `{{ 'Result: {{count}}' | translate: { count: value } }}`
+- Every user-visible string must be wrapped
+- Reference: https://cumulocity.com/codex/components/application-and-system/internationalization/overview
+
+---
+
+## Error Handling
+
+- **Never leave catch blocks empty** — propagate, display via `AlertService.danger()` with translations, or comment why swallowed
+- API failures must be both logged to console AND displayed to the user
+
+---
+
+## Accessibility
+
+WCAG 2.1 Level AA compliance is **mandatory** for all UI work.
+
+### Semantic HTML & Structure
+
+- Use semantic elements (`<nav>`, `<main>`, `<section>`, `<article>`, `<aside>`, `<header>`, `<footer>`) — never `<div>` soup
+- Heading levels (`<h1>`–`<h6>`) must follow a logical hierarchy — never skip levels for styling
+- Use `<button>` for actions and `<a>` for navigation — never `<div (click)>` or `<span (click)>`
+- Lists of items must use `<ul>`/`<ol>`/`<li>` — not styled divs
+- Tables must have `<th>` with `scope` attributes; use `<caption>` for table purpose
+
+### Keyboard Operability (2.1.1, 2.1.2, 2.1.4)
+
+- All interactive elements must be reachable and operable via keyboard alone
+- Custom interactive elements need `tabindex="0"` and key event handlers (`Enter`, `Space`, `Escape`, arrow keys as appropriate)
+- **No keyboard traps** — focus must always be escapable (modals must return focus to trigger on close)
+- Manage focus programmatically on route changes and after dynamic content insertion
+- Character key shortcuts (single letter) must be remappable, disableable, or only active on focus
+
+### Focus Management
+
+- Focus order must follow a logical reading sequence (`tabindex` > 0 is **forbidden**)
+- Focus must be visible at all times — never `outline: none` without a visible replacement
+- Trap focus inside modals/dialogs while open; restore focus to trigger element on close
+- Use `cdkTrapFocus` or `cdkFocusInitial` from `@angular/cdk/a11y` for focus trapping
+- After dynamic content changes (route navigation, drawer open/close), move focus to the new content
+
+### Color & Contrast (1.4.1, 1.4.3, 1.4.11)
+
+- **Text contrast:** minimum 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold)
+- **Non-text contrast:** UI components and graphical objects need minimum 3:1 contrast against adjacent colors
+- **Never use color alone** to convey information — always pair with text, icons, or patterns (e.g., error states need icon + color + text, not just red)
+- Use design tokens exclusively — they are pre-validated for contrast compliance, never add custom colors
+
+### Forms & Input (1.3.5, 3.3.1, 3.3.2, 3.3.3, 3.3.4)
+
+- Every form control must have a visible `<label>` associated via `for`/`id` — never placeholder-only labels
+- Use `autocomplete` attributes on fields collecting personal data (`name`, `email`, `tel`, `street-address`, etc.)
+- Error messages must: identify the field in error, describe the error, and suggest correction
+- Display errors with `role="alert"` or `aria-live="assertive"` so screen readers announce them
+- Group related controls with `<fieldset>` and `<legend>`
+- Required fields must be marked with `aria-required="true"` and a visible indicator
+
+### Images & Icons (1.1.1)
+
+- Informative images: `alt` text describing content or function
+- Decorative images/icons: `aria-hidden="true"` and empty `alt=""`
+- Icon-only buttons must have `aria-label` or visually hidden text: `<button aria-label="{{ 'Delete item' | translate }}"><i [c8yIcon]="'minus-circle'" aria-hidden="true"></i></button>`
+- Complex images (charts, diagrams): provide text alternative via `aria-describedby` pointing to a description
+
+### Dynamic Content & Live Regions (4.1.3)
+
+- Status messages (success, info, warnings) must use `role="status"` or `aria-live="polite"`
+- Urgent messages (errors, alerts) must use `role="alert"` or `aria-live="assertive"`
+- Loading states: announce start and end — e.g., `aria-busy="true"` on the container, announce completion
+- Content that updates without page reload must notify assistive technology
+- Never auto-update content faster than the user can read it; provide pause/stop controls for auto-rotating content
+
+### Text & Content (1.4.4, 1.4.10, 1.4.12, 1.4.13)
+
+- Text must be resizable up to 200% without loss of content or functionality
+- Content must reflow at 320px viewport width without horizontal scrolling
+- No loss of content when users override text spacing (line height 1.5x, letter spacing 0.12em, word spacing 0.16em)
+- Content revealed on hover/focus (tooltips) must be: dismissible (Esc), hoverable (mouse can reach it), and persistent (stays until dismissed)
+
+### ARIA Usage
+
+- **First rule of ARIA:** don't use ARIA if a native HTML element provides the semantics (`<button>` over `<div role="button">`)
+- Use `aria-label` or `aria-labelledby` for elements without visible text labels
+- Use `aria-describedby` for supplementary descriptions (help text, constraints)
+- Use `aria-expanded`, `aria-controls`, `aria-haspopup` for disclosure widgets
+- Custom widgets (tabs, trees, comboboxes) must implement the full [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) keyboard and role pattern
+- Use `aria-current="page"` for active navigation links
+
+### Testing Checklist
+
+- **Keyboard-only:** tab through entire page, operate every control, escape every modal
+- **Screen reader:** test critical flows with VoiceOver (macOS) — ensure all content is announced
+- **Zoom:** verify layout at 200% zoom and 320px viewport
+- **Color:** inspect with simulated color-blindness (DevTools → Rendering → Emulate vision deficiencies)
+- **Automated:** run `axe-core` or Lighthouse accessibility audit — zero violations is the baseline, not the goal

package/dist/templates/ai-configs/windsurf/rules/unit-tests.instructions.md

@@ -0,0 +1,172 @@
+---
+name: "Jest Unit Testing Guide"
+description: "Instructions for Jest unit tests (TypeScript)"
+applyTo: "**/*.spec.ts"
+paths: ["**/*.spec.ts"]
+---
+
+# Unit Testing Guide
+
+## Overview
+Unit tests use Jest with TestBed for Angular component setup and jest.fn() for mocking services.
+
+# Common
+
+## Test File Location
+- Unit test files are co-located with the code they test
+- Use `.spec.ts` extension for test files
+- Example: `my-component.ts` → `my-component.spec.ts`
+
+## Basic Test Structure
+```typescript
+describe('ComponentName', () => {
+  let component: ComponentName;
+  let fixture: ComponentFixture<ComponentName>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [ComponentName],
+      providers: [/* services */]
+    }).compileComponents();
+    fixture = TestBed.createComponent(ComponentName);
+    component = fixture.componentInstance;
+  });
+
+  test('should do something specific', () => {
+    fixture.detectChanges();
+    expect(actual).toBe(expected);
+  });
+});
+```
+
+**Key points:**
+- Always use `async` on `beforeEach` and `await` + `.compileComponents()` on `configureTestingModule()` to properly compile components
+- Always call `fixture.detectChanges()` before asserting anything about the component (triggers Angular initialization and change detection)
+
+## Angular Testing
+- Test component behavior, not implementation details
+- Test DOM interactions through the fixture using `fixture.detectChanges()`
+- For async operations: use `fixture.whenStable()` to wait for pending async tasks or `async`/`waitForAsync` and `fakeAsync`
+
+## Best Practices
+- **Descriptive test names**: Use "should..." pattern in it() names
+- **Be concise**: Keep tests to as few lines as possible. Avoid unnecessary variable declarations. Use helper functions for common test data.
+- **Structure tests logically**: Group related tests using nested `describe` blocks
+- **Mock external dependencies**: Don't test third-party code
+- **Test user behavior**: Focus on what users experience, not implementation details
+- **Avoid arbitrary sleeps**: Do NOT use `setTimeout` in tests — instead use `fixture.whenStable()` or `await` for async operations
+- **Don't duplicate**: Use `beforeEach` for common setup, or extract helper functions
+- **Avoid brittleness**: Don't depend on exact backend data structure details that may change
+- **Always call `detectChanges()` before assertions**: Angular change detection must run before testing component state or DOM
+- **Mock comprehensively**: If a service has 10 public methods and your component calls 8 of them, mock all 8 in the test setup to avoid runtime errors later
+
+## Common Pitfalls to Avoid
+- ❌ **Forgetting `async` and `.compileComponents()`**: `beforeEach(() => { ... })` without `async`/`await` leaves components uncompiled
+- ❌ **Missing `fixture.detectChanges()`**: Component won't initialize without this; properties will be undefined
+- ❌ **Incomplete service mocks**: Mocking only some methods causes "is not a function" errors on unmocked methods
+- ❌ **Wrong mock return types**: Returning `[]` when the method returns `{ data: [], paging: {} }` causes destructuring errors
+- ❌ **Not providing all dependencies**: Missing providers (e.g., `TranslateService`) causes "No provider found" errors
+- ✅ **DO**: Mock all methods, use correct async patterns, always call `detectChanges()`, verify return types match the real service
+
+## Common Test Patterns
+```typescript
+// Testing component initialization
+it('should initialize with default values', () => {
+  fixture.detectChanges();
+  expect(component.propertyName).toBe(expectedValue);
+});
+
+// Testing async operations
+it('should load data on init', async () => {
+  fixture.detectChanges();
+  await fixture.whenStable();
+  fixture.detectChanges();
+  expect(component.data).toBeDefined();
+});
+
+// Testing user interactions
+it('should emit event when button clicked', () => {
+  fixture.detectChanges();
+  jest.spyOn(component.outputEvent, 'emit');
+  fixture.nativeElement.querySelector('button').click();
+  expect(component.outputEvent.emit).toHaveBeenCalled();
+});
+```
+
+## TypeScript in Tests
+- Use proper types, avoid `any`
+- Type your test data and mocks
+- Use interfaces from the application code
+- Enable strict mode for better type safety
+
+# Setup & Mocking
+
+## Mocking
+
+### TestBed Setup with jest.fn()
+
+Use **TestBed.configureTestingModule** for component setup and **jest.fn()** for mock service objects:
+
+```typescript
+beforeEach(async () => {
+  await TestBed.configureTestingModule({
+    imports: [MyComponent],
+    providers: [
+      {
+        provide: MyService,
+        useValue: {
+          getData: jest.fn().mockResolvedValue(data),
+          logout: jest.fn()
+        }
+      }
+    ]
+  }).compileComponents();
+  fixture = TestBed.createComponent(MyComponent);
+  component = fixture.componentInstance;
+});
+```
+
+**Important mocking guidelines:**
+- **Mock all public methods** that the component or its children might call, not just a few
+- **Match return types exactly**: If a method returns `Promise<T>`, use `.mockResolvedValue(T)`; if it returns an object with properties, return a properly structured object (e.g., `{ data: [], paging: {} }`)
+- **Use `.mockResolvedValue()` for async methods** to return promises correctly
+- **Use `.mockReturnValue()` for synchronous methods**
+- **Type your mocks** to catch missing methods early: `useValue: {...} as jest.Mocked<MyService>`
+
+### Spying on Component/Service Methods
+
+```typescript
+const service = TestBed.inject(MyService);
+jest.spyOn(service, 'getData').mockReturnValue(value);
+
+// Or for component methods:
+jest.spyOn(component, 'onSubmit');
+component.handleForm();
+expect(component.onSubmit).toHaveBeenCalled();
+```
+
+## Matchers
+- `toBe()` - Strict equality (===)
+- `toEqual()` - Deep equality
+- `toBeTruthy()` / `toBeFalsy()`
+- `toContain()` - Array/string contains
+- `toHaveBeenCalled()` - Spy was called
+- `toHaveBeenCalledWith(args)` - Spy called with specific arguments
+- `toHaveLength(n)` - Array/string length
+- `toThrow()` / `toThrowError()` - Exception testing
+- See [Jest matchers documentation](https://jestjs.io/docs/expect) for complete list
+
+## Running Tests
+- Run specific file: `yarn jest my-component.spec.ts`
+- Run with watch mode: `yarn jest --watch my-component.spec.ts`
+- Run single test suite: `yarn jest my-component.spec.ts -t '^SuiteName(\\s.*)?$'`
+- Debug race conditions: `yarn jest my-component.spec.ts --testNamePattern="Test Name" --maxWorkers=1`
+
+## Coverage
+- Aim for high coverage but focus on meaningful tests
+- Ensure exception cases are covered where possible
+- Focus on critical paths and edge cases
+
+## Resources
+- Jest documentation: https://jestjs.io/
+- Angular testing guide: https://angular.dev/guide/testing

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@c8y/websdk",
-  "version": "1023.81.2",
+  "version": "1023.82.0",
   "description": "Allows to scaffold a Cumulocity IoT application with ng add @c8y/websdk",
   "license": "Apache-2.0",
   "scripts": {
     "test": "jest",
-    "build": "rimraf ./dist && tsc -p ./tsconfig.json && yarn build:applist && mkdirp ./dist/ng-add/ && yarn copy:schemas",
+    "build": "rimraf ./dist && tsc -p ./tsconfig.json && yarn build:applist && mkdirp ./dist/ng-add/ && yarn copy:schemas && yarn copy:ai-configs",
     "copy:schemas": "npx ncp ./collection.json ./dist/collection.json && npx ncp ./ng-add/ng-add.json ./dist/ng-add/ng-add.json",
+    "copy:ai-configs": "ts-node ./tools/copy-ai-configs.ts",
     "build:applist": "ts-node ./tools/app-list-extract.ts"
   },
   "schematics": "./dist/collection.json",