@c8y/websdk 1023.81.2 → 1023.82.0

package/dist/templates/ai-configs/claude/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/dist/templates/ai-configs/cursor/cursor.mdc

@@ -0,0 +1,98 @@
+## Project Identity
+
+**Cumulocity IoT Web Application** — custom web frontend built with the Cumulocity Web SDK. Extends the Cumulocity IoT platform with custom features and integrations.
+
+- **Stack:** Angular 20, TypeScript 5.9.3, RxJS 7.8, Jest 30, Cypress 15, ESLint (airbnb-base + angular-eslint)
+- **Core Libraries:** `@c8y/ngx-components`, `@c8y/client`, `@c8y/toolkit`, `@c8y/devkit`, `@c8y/bootstrap`
+- **Structure:** Standard Angular CLI application scaffolded with `ng add @c8y/websdk`
+
+---
+
+## 🛑 MANDATORY WORKFLOW: UI Planning & Implementation
+
+**STOP: Before analyzing, planning, designing, OR implementing ANY UI feature/component, you MUST complete this workflow. No exceptions.**
+
+### Step 1: Fetch Codex Documentation (REQUIRED BEFORE PLANNING)
+
+When the user requests ANY UI work (planning, design, implementation), your **FIRST ACTION** must be:
+
+1. **Fetch** https://cumulocity.com/codex/llms.txt
+2. **Search** the content for relevant component keywords (modal, button, form, table, etc.)
+3. **If found:** Read the specific `.md` documentation file like `https://cumulocity.com/codex/components/forms/editor.md`
+4. **Read and analyze** the documentation content
+5. **Locate examples** in the public tutorial repository: 
+e.g. for file path './packages/tutorial/src/selector/asset-selector-example/tree-options/asset-selector-tree-example.component.ts' get file from 
+'https://github.com/Cumulocity-IoT/tutorial/tree/main/src/selector/asset-selector-example/tree-options/asset-selector-tree-example.component.ts'
+6. **Read example code** to understand the official pattern
+
+**⛔ INVALID:** 
+- ❌ "I'll list the Codex URL as a resource to review later"
+- ❌ "The plan should include fetching the documentation"
+- ❌ "Before implementation, we need to review the Codex"
+- ❌ Making a plan without actually fetching and reading documentation
+
+**✅ VALID:**
+- ✓ Fetch llms.txt → Find modal docs → Read content → Find tutorial examples → Read example code → Then create plan
+
+### Step 2: Check for Existing Components
+
+After reviewing documentation:
+
+1. Search `@c8y/ngx-components` for existing implementations
+2. Use a matching Cumulocity component if one exists — **never build custom equivalents**
+3. Only proceed with custom solution if nothing suitable exists
+
+### Step 3: Plan or Implement
+
+Only after completing Steps 1-2, proceed with planning or implementation.
+
+---
+
+## Universal Rules — TypeScript
+
+- Target is ES2022; do not use syntax unavailable in ES2022
+- Enable strict mode where possible; use explicit types or `unknown` with narrowing guards
+- Avoid `any`; prefer explicit types
+- Use path aliases for imports: `@c8y/ngx-components`, `@c8y/client`, `@c8y/devkit`, `@c8y/options`
+- `experimentalDecorators: true` is set globally; Angular decorator syntax is valid as-is
+
+## Universal Rules — Cumulocity Platform
+
+### Other rules
+
+- Use `@c8y/client` services for all Cumulocity REST calls — do **not** use `HttpClient` directly for platform endpoints
+- Check `@c8y/ngx-components` before building custom UI components — it exports a large shared library. Search by visual functionality in [Codex](https://cumulocity.com/codex)
+- Wrap every user-facing string with `C8yTranslatePipe` (`| translate`) or `TranslateService`:
+  - ✅ `{{ 'Save' | translate }}`  ❌ `Save`
+
+## Angular Patterns
+
+- All new components must be **standalone** (`standalone: true`) — do not create NgModule-based components
+- Prefer `ChangeDetectionStrategy.OnPush` for new components (no project-wide enforcement, but scale demands it)
+- Constructor injection and `inject()` function are both present; either is acceptable
+- Manage subscriptions with `async` pipe or `takeUntilDestroyed()` — avoid bare `unsubscribe()` without `ngOnDestroy`
+- Use signals for local component state
+- Consider extracting child components when template exceeds ~150 lines or class exceeds ~200 lines
+
+## Code Quality (PR Review Focus)
+
+- Remove `console.log` / `console.debug` before commit; `console.error` acceptable in caught exceptions
+- Flag methods exceeding ~40 lines — consider decomposition
+- Remove commented-out code; use git history for recovery
+- New features should have `*.spec.ts` unit tests; new user flows should have Cypress coverage
+- Document types, methods and properties that are not self-explanatory; don't explain ones that are obvious
+- Test use cases that are truly worth testing, do not create test cases just for the sake of tests volume or coverate 
+
+## Security Checks
+
+- Flag hardcoded tenant IDs, device IDs, credentials, or API tokens — use `Cypress.env()` in tests, env config in production
+- Review components rendering dynamic device/asset data for XSS: prefer `{{ }}` over `[innerHTML]` with unescaped values
+- Treat IoT payload data as untrusted — validate and sanitize before display
+- Do not expose internal hostnames or credentials in client-side code
+
+## What NOT to Flag
+
+- **Import order** — managed by ESLint
+- **Quote style / semicolons** — ESLint enforces single quotes and required semicolons
+- **Trailing commas on function parameters** — ESLint explicitly disallows them
+- **`skipLibCheck: true`** in tsconfig — intentional project setting

package/dist/templates/ai-configs/cursor/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