# Security Best Practices Standards for Angular
This document outlines security best practices for Angular applications. It provides guidelines and actionable standards to protect against common vulnerabilities and implement secure coding patterns. These standards are tailored for the latest versions of Angular.
## 1. General Security Principles
### 1.1 Principle of Least Privilege
**Standard:** Grant users and components only the minimal level of access necessary to perform their tasks.
* **Do This:** Restrict API access based on user roles and permissions. Implement granular access control mechanisms.
* **Don't Do This:** Grant broad admin privileges unless absolutely necessary.
**Why:** Reduces the impact of potential security breaches. If an account or component is compromised, the attacker's access is limited.
**Example (Role-based Auth Guard):**
"""typescript
import { Injectable } from '@angular/core';
import { CanActivate, ActivatedRouteSnapshot, RouterStateSnapshot, Router } from '@angular/router';
import { AuthService } from './auth.service';
@Injectable({
providedIn: 'root'
})
export class RoleGuard implements CanActivate {
constructor(private authService: AuthService, private router: Router) {}
canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean {
const expectedRole = route.data['expectedRole']; // Get expected role from route data
const userRole = this.authService.getRole();
if (!this.authService.isAuthenticated() || userRole !== expectedRole) {
this.router.navigate(['login']);
return false;
}
return true;
}
}
"""
**Explanation:** This "RoleGuard" checks if the user has the required role to access a route. Route definitions specify the "expectedRole" in their "data" property. The "AuthService" retrieves the user's role. If the user is not authenticated or doesn't have the correct role, they're redirected to the login page.
### 1.2 Defense in Depth
**Standard:** Implement multiple layers of security controls to protect against vulnerabilities.
* **Do This:** Combine input validation, output encoding, authentication, authorization, and other security measures.
* **Don't Do This:** Rely on a single security mechanism for protection.
**Why:** If one security layer fails, the other layers still provide protection against attacks.
**Example:**
"""typescript
// Component
import { Component } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';
import { DomSanitizer } from '@angular/platform-browser';
@Component({
selector: 'app-comment',
template: "
Submit
"
})
export class CommentComponent {
commentForm: FormGroup;
safeComment: any = '';
constructor(private fb: FormBuilder, private sanitizer: DomSanitizer) {
this.commentForm = this.fb.group({
comment: ['', Validators.required] // Input Validation
});
}
onSubmit() {
if (this.commentForm.valid) {
const comment = this.commentForm.value.comment;
// Output Sanitization using DomSanitizer
this.safeComment = this.sanitizer.bypassSecurityTrustHtml(comment);
// ... send data to the server ...
}
}
}
"""
**Explanation:**
* **Input Validation:** The "Validators.required" ensures that the comment field is not empty. More complex validations should be added for characters allowed, maximum length, etc.
* **Output Sanitization:** The "DomSanitizer" is used to sanitize the comment before displaying it to the user. This will prevent cross-site scripting (XSS) attacks.
### 1.3 Secure by Default
**Standard:** Configure applications with secure settings from the start.
* **Do This:** Enable HTTPS, use strong encryption algorithms, and disable unnecessary features.
* **Don't Do This:** Rely on developers to remember to enable security features during deployment or configuration.
**Why:** Reduces the chance of misconfiguration vulnerabilities.
## 2. Preventing Cross-Site Scripting (XSS)
### 2.1 Output Encoding/Sanitization
**Standard:** Sanitize or encode all user-supplied data before rendering it in the DOM.
* **Do This:** Use Angular's built-in "DomSanitizer" to sanitize HTML, style, and URL contexts.
* **Don't Do This:** Directly inject unsanitized user input into templates using "innerHTML" or similar methods without sanitization.
**Why:** Prevents attackers from injecting malicious scripts into your application.
**Example:**
"""typescript
import { Component, SecurityContext } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
@Component({
selector: 'app-xss-example',
template: "
"
})
export class XssExampleComponent {
userInput = '';
sanitizedHtml: any;
constructor(private sanitizer: DomSanitizer) {
this.sanitizedHtml = this.sanitizer.sanitize(SecurityContext.HTML, this.userInput);
}
}
"""
**Explanation:** The "DomSanitizer.sanitize()" method escapes or removes potentially dangerous HTML tags and attributes from the user input, making it safe to render. The "SecurityContext" parameter specifies the type of content being sanitized.
### 2.2 Bypassing Security (Use with Extreme Caution)
**Standard:** Only bypass Angular's built-in security mechanisms when absolutely necessary, and understand the risks involved.
* **Do This:** Use "bypassSecurityTrustHtml", "bypassSecurityTrustStyle", etc., only when you have complete control over the input *and* you are certain it is safe. Document *why* bypassing security is required in these specific cases.
* **Don't Do This:** Casually bypass security measures without understanding the potential consequences.
**Why:** Angular's security mechanisms are in place to protect your application from XSS attacks. Bypassing them can introduce vulnerabilities.
**Example (when bypassing is necessary - VERY RARE):**
"""typescript
import { Component } from '@angular/core';
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
@Component({
selector: 'app-safe-html-example',
template: ""
})
export class SafeHtmlExampleComponent {
trustedHtml: SafeHtml;
constructor(private sanitizer: DomSanitizer) {
// ONLY do this if you fully trust the source of the HTML.
this.trustedHtml = this.sanitizer.bypassSecurityTrustHtml('<p>This is trusted HTML.</p>');
}
}
"""
**Explanation:** In this rare case, the developer *knows* that the HTML is safe (e.g., it's coming from a trusted source and is part of the application's core content). This bypasses the normal sanitization process. **Document clear justification as to why this bypass is necessary.**
### 2.3 Content Security Policy (CSP)
**Standard:** Implement a Content Security Policy (CSP) to control the sources from which the browser is allowed to load resources.
* **Do This:** Configure your web server to send the "Content-Security-Policy" HTTP header. Start with a restrictive policy and gradually relax it as needed.
* **Don't Do This:** Use "unsafe-inline" or "unsafe-eval" unless absolutely necessary. Avoid using wildcards (*) for allowed sources.
**Why:** CSP helps prevent XSS attacks by restricting the resources that the browser is allowed to load.
**Example (CSP Header):**
"""
Content-Security-Policy: default-src 'self'; script-src 'self' https://apis.google.com; style-src 'self' https://fonts.googleapis.com; img-src 'self' data:; font-src 'self' https://fonts.gstatic.com;
"""
**Explanation:** This CSP allows:
* Loading resources from the same origin ("'self'") by default.
* Loading scripts from the same origin and "https://apis.google.com".
* Loading styles from the same origin and "https://fonts.googleapis.com".
* Loading images from the same origin and data URLs.
* Loading fonts from the same origin and "https://fonts.gstatic.com".
## 3. Preventing Cross-Site Request Forgery (CSRF)
### 3.1 CSRF Tokens
**Standard:** Implement CSRF protection using tokens.
* **Do This:** Generate a unique CSRF token on the server, include it in the user's session, embed it within your Angular forms (hidden field), and validate the token on the server before processing any state-changing requests.
* **Don't Do This:** Rely solely on the "SameSite" cookie attribute for CSRF protection (while "SameSite" is helpful, it does not provide full protection, especially with older browsers). Do not transmit the CSRF token in a cookie itself.
**Why:** Prevents attackers from forging requests on behalf of authenticated users.
**Example:**
**Backend (Node.js with Express):**
"""javascript
const express = require('express');
const csrf = require('csurf');
const cookieParser = require('cookie-parser');
const app = express();
app.use(cookieParser());
const csrfProtection = csrf({ cookie: true }); // Enable CSRF protection
app.use(express.urlencoded({ extended: false }));
app.get('/form', csrfProtection, (req, res) => {
// pass the CSRF token to the view
res.send("
Comment:
Submit
");
});
app.post('/process', csrfProtection, (req, res) => {
console.log('Comment received:', req.body.comment);
res.send('Comment submitted!');
});
app.listen(3000, () => console.log('Server listening on port 3000'));
"""
**Angular Frontend:**
"""typescript
import { HttpClient, HttpHeaders } from '@angular/common/http';
import { Injectable } from '@angular/core';
@Injectable({
providedIn: 'root'
})
export class CommentService {
constructor(private http: HttpClient) {}
submitComment(comment: string, csrfToken: string) {
const headers = new HttpHeaders({
'Content-Type': 'application/x-www-form-urlencoded',
'X-CSRF-TOKEN': csrfToken // Send token as a custom header
});
const body = "comment=${comment}&_csrf=${csrfToken}"; //CSRF value added to message body
return this.http.post('/process', body, { headers: headers });
}
}
"""
**Explanation:**
1. **Server-Side CSRF Token Generation:** The server generates a unique CSRF token for each authenticated user session. This token is stored server-side (session, database, etc.). The token is sent to the client (typically embedded within the HTML).
2. **Angular Form Submission:** The Angular application retrieves the CSRF token (e.g., from a cookie, local storage, or provided directly in the returned HTML). It then includes it as a *header* (or POST parameter) in subsequent requests (POST, PUT, DELETE, etc.) that modify data.
3. **Server-Side Validation:** The server *always* validates the CSRF token on the server side before processing any state-changing request. If the token is missing, invalid, or doesn't match the expected value, the request is rejected.
### 3.2 "SameSite" Cookie Attribute
**Standard:** Use the "SameSite" cookie attribute to mitigate CSRF attacks.
* **Do This:** Set the "SameSite" attribute to "strict" or "lax" for cookies that are used for authentication and session management. *In addition* to CSRF tokens.
* **Don't Do This:** Rely solely on "SameSite" cookies without any other CSRF protection mechanism.
"""javascript
// Setting a cookie with SameSite attribute in Express
app.get('/set-cookie', (req, res) => {
res.cookie('session', 'your_session_value', { sameSite: 'strict', secure: true }); // secure: true is for HTTPS
res.send('Cookie set');
});
"""
**Explanation:**
* **"Strict":** The cookie will only be sent in requests originating from the same site. Provides the strongest CSRF protection, but might break some legitimate cross-site navigation (e.g., following a link from an email).
* **"Lax":** The cookie will be sent with top-level navigations and GET requests that do not change the server's state. Offers a balance between security and usability.
## 4. Authentication and Authorization
### 4.1 Secure Password Storage
**Standard:** Never store passwords in plain text.
* **Do This:** Hash passwords using a strong hashing algorithm (e.g., bcrypt, scrypt, Argon2) with a unique salt for each password.
* **Don't Do This:** Use weak hashing algorithms (e.g., MD5, SHA1) or store passwords in plain text.
**Why:** Prevents attackers from obtaining user passwords if the database is compromised.
**Example (Backend Password Hashing with bcrypt):**
"""javascript
const bcrypt = require('bcrypt');
async function hashPassword(password) {
const saltRounds = 10; // Higher is more secure, but slower
const hashedPassword = await bcrypt.hash(password, saltRounds);
return hashedPassword;
}
async function comparePassword(password, hashedPassword) {
const match = await bcrypt.compare(password, hashedPassword);
return match;
}
"""
**Explanation:**
* "bcrypt.hash()" generates a salt and hashes the password. The salt is stored along with the hash.
* "bcrypt.compare()" compares a plain text password with the stored hash, including the salt.
### 4.2 Multi-Factor Authentication (MFA)
**Standard:** Implement MFA for sensitive accounts and applications.
* **Do This:** Offer users the option to enable MFA using methods such as one-time passwords (OTP), biometric authentication, or hardware security keys.
* **Don't Do This:** Rely solely on passwords for authentication.
**Why:** Adds an extra layer of security, making it more difficult for attackers to compromise accounts.
### 4.3 JSON Web Tokens (JWT) Best Practices
**Standard:** Use JWTs securely for authentication and authorization.
* **Do This:**
* Use a strong secret key to sign JWTs on the server.
* Verify the JWT signature on the server before processing any requests.
* Use short expiration times for JWTs.
* Store JWTs securely (e.g., using HTTP-only cookies or in-memory storage).
* Consider using refresh tokens for long-lived sessions.
* **Don't Do This:**
* Store sensitive information in the JWT payload.
* Use JWTs without a signature.
* Store JWTs in local storage (vulnerable to XSS).
* Use long expiration times for JWTs without proper revocation mechanisms.
**Why:** JWTs can be a convenient way to authenticate and authorize users, but they must be used securely to avoid vulnerabilities.
**Example (Generating and Verifying JWTs with Node.js):**
"""javascript
const jwt = require('jsonwebtoken');
const secretKey = 'your-secret-key'; // Replace with a strong, randomly generated key
function generateToken(payload) {
const token = jwt.sign(payload, secretKey, { expiresIn: '1h' });
return token;
}
function verifyToken(token) {
try {
const decoded = jwt.verify(token, secretKey);
return decoded;
} catch (err) {
return null; // Token is invalid or expired
}
}
"""
**Explanation:**
* "jwt.sign()" creates a JWT with the specified payload, secret key, and expiration time.
* "jwt.verify()" verifies the JWT signature and decodes the payload.
## 5. Data Security
### 5.1 Data Encryption
**Standard:** Encrypt sensitive data at rest and in transit.
* **Do This:** Use HTTPS to encrypt data in transit. Encrypt sensitive data stored in databases or files.
* **Don't Do This:** Transmit sensitive data over unencrypted HTTP connections. Store sensitive data in plain text.
**Why:** Protects data from unauthorized access if it is intercepted or stolen.
### 5.2 Input Validation
**Standard:** Validate all user inputs on both the client-side and server-side.
* **Do This:** Use Angular's built-in form validation features to validate inputs on the client-side. Implement server-side validation to prevent malicious inputs.
* **Don't Do This:** Rely solely on client-side validation, as it can be bypassed by attackers.
**Why:** Prevents attackers from injecting malicious data into your application.
**Example:**
"""typescript
import { Component } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';
@Component({
selector: 'app-validation-example',
template: "
Submit
"
})
export class ValidationExampleComponent {
myForm: FormGroup;
constructor(private fb: FormBuilder) {
this.myForm = this.fb.group({
email: ['', [Validators.required, Validators.email]]
});
}
onSubmit() {
if (this.myForm.valid) {
console.log('Form submitted with value:', this.myForm.value);
}
}
}
"""
**Explanation:**
* Provides client-side validation that email is required and in the correct format. **Important note:** You still MUST validate on the server-side. Client side validation is a usability feature, not a security feature.
### 5.3 Rate Limiting
**Standard:** Implement rate limiting to protect against brute-force attacks, DDoS attacks, and API abuse.
* **Do This:** Limit the number of requests that a user or IP address can make within a specific time period.
* **Don't Do This:** Allow unlimited requests to sensitive endpoints.
**Why:** Prevents attackers from overwhelming your server or performing brute-force attacks.
**Example (Rate Limiting with Express):**
"""javascript
const rateLimit = require("express-rate-limit");
const limiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
max: 100, // Limit each IP to 100 requests per windowMs
message: "Too many requests from this IP, please try again after 15 minutes"
});
app.use(limiter); // Apply the rate limiting middleware to all routes
"""
## 6. Dependency Management and Security Audits
### 6.1 Keep Dependencies Up-to-Date
**Standard:** Regularly update your Angular dependencies to the latest versions.
* **Do This:** Use "npm update" or "yarn upgrade" to update your dependencies. Use tools to automate dependency updates (e.g., Dependabot).
* **Don't Do This:** Use outdated dependencies that contain known security vulnerabilities.
**Why:** New versions of dependencies often include security fixes and performance improvements.
### 6.2 Security Audits
**Standard:** Regularly perform security audits of your Angular application and its dependencies.
* **Do This:** Use "npm audit" or "yarn audit" to identify vulnerabilities in your dependencies. Review your code for potential security flaws. Consider hiring a security expert to perform a penetration test.
* **Don't Do This:** Ignore security warnings or vulnerabilities.
**Why:** Helps identify and fix security issues before they can be exploited by attackers.
## 7. Error Handling and Logging
### 7.1 Secure Error Handling
**Standard:** Handle errors gracefully and avoid exposing sensitive information in error messages.
* **Do This:** Log errors on the server-side. Show generic error messages to the user. Avoid displaying stack traces or other sensitive information in the client.
* **Don't Do This:** Display detailed error messages to the user, as this can reveal information about your application's internal workings.
**Why:** Prevents attackers from gathering information about your application by exploiting error messages.
### 7.2 Secure Logging
**Standard:** Log security-related events and activities.
* **Do This:** Log authentication attempts, authorization failures, and other security-related events.
* **Don't Do This:** Log sensitive data (e.g., passwords, credit card numbers). Store logs securely.
**Why:** Provides valuable information for security monitoring, incident response, and forensic analysis.
## 8. Regular Security Training
**Standard:** Provide regular security training to your development team.
* **Do This:** Train your developers on common web application vulnerabilities, secure coding practices, and the latest security threats.
* **Don't Do This:** Assume that your developers already know everything they need to know about security.
**Why:** Helps developers understand security risks and write more secure code.
By following these security best practices, you can significantly reduce the risk of security vulnerabilities in your Angular applications. Always stay up-to-date with the latest security threats and best practices, and adapt these guidelines as needed.
danielsogl
Created Mar 6, 2025
This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.
The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.
Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.
# Project Overview project: name: 'Your Project Name' description: 'Brief project description' stack: - technology: 'Framework/Language' version: 'X.Y.Z' - technology: 'Database' version: 'X.Y.Z'
# Code Standards standards: style: - 'Use consistent indentation (2 spaces)' - 'Follow language-specific naming conventions' documentation: - 'Include JSDoc comments for all functions' - 'Maintain up-to-date README files' testing: - 'Write unit tests for all new features' - 'Maintain minimum 80% code coverage'
# Security Guidelines security: authentication: - 'Implement proper token validation' - 'Use environment variables for secrets' dataProtection: - 'Sanitize all user inputs' - 'Implement proper error handling'
Be Specific
Maintain Organization
Regular Updates
# Common Patterns Example patterns: components: - pattern: 'Use functional components by default' - pattern: 'Implement error boundaries for component trees' stateManagement: - pattern: 'Use React Query for server state' - pattern: 'Implement proper loading states'
Commit the Rules
.clinerules in version controlTeam Collaboration
Rules Not Being Applied
Conflicting Rules
Performance Considerations
# Basic .clinerules Example project: name: 'Web Application' type: 'Next.js Frontend' standards: - 'Use TypeScript for all new code' - 'Follow React best practices' - 'Implement proper error handling' testing: unit: - 'Jest for unit tests' - 'React Testing Library for components' e2e: - 'Cypress for end-to-end testing' documentation: required: - 'README.md in each major directory' - 'JSDoc comments for public APIs' - 'Changelog updates for all changes'
# Advanced .clinerules Example project: name: 'Enterprise Application' compliance: - 'GDPR requirements' - 'WCAG 2.1 AA accessibility' architecture: patterns: - 'Clean Architecture principles' - 'Domain-Driven Design concepts' security: requirements: - 'OAuth 2.0 authentication' - 'Rate limiting on all APIs' - 'Input validation with Zod'
# Angular Guidelines Use this guidelines when working with Angular related code. ## 1. Core Architecture - **Standalone Components:** Components, directives, and pipes are standalone by default. The `standalone: true` flag is no longer required and should be omitted in new code (Angular v17+ and above). - **Strong Typing:** TypeScript types, interfaces, and models provide type safety throughout the codebase - **Single Responsibility:** Each component and service has a single, well-defined responsibility - **Rule of One:** Files focus on a single concept or functionality - **Reactive State:** Signals provide reactive and efficient state management - **Dependency Injection:** Angular's DI system manages service instances - **Function-Based DI:** Use function-based dependency injection with the `inject()` function instead of constructor-based injection in all new code. Example: ```typescript import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; export class MyService { private readonly http = inject(HttpClient); // ... } ``` - **Lazy Loading:** Deferrable Views and route-level lazy loading with `loadComponent` improve performance - **Directive Composition:** The Directive Composition API enables reusable component behavior - **Standalone APIs Only:** Do not use NgModules, CommonModule, or RouterModule. Import only required standalone features/components. - **No Legacy Modules:** Do not use or generate NgModules for new features. Migrate existing modules to standalone APIs when possible. ## 2. Angular Style Guide Patterns - **Code Size:** Files are limited to 400 lines of code - **Single Purpose Files:** Each file defines one entity (component, service, etc.) - **Naming Conventions:** Symbols have consistent, descriptive names - **Folder Structure:** Code is organized by feature-based folders - **File Separation:** Templates and styles exist in their own files for components - **Property Decoration:** Input and output properties have proper decoration - **Component Selectors:** Component selectors use custom prefixes and kebab-case (e.g., `app-feature-name`) - **No CommonModule or RouterModule Imports:** Do not import CommonModule or RouterModule in standalone components. Import only the required standalone components, directives, or pipes. ## 3. Input Signal Patterns - **Signal-Based Inputs:** The `input()` function creates InputSignals: ```typescript // Current pattern readonly value = input(0); // Creates InputSignal // Legacy pattern @Input() value = 0; ``` - **Required Inputs:** The `input.required()` function marks inputs as mandatory: ```typescript readonly value = input.required<number>(); ``` - **Input Transformations:** Transformations convert input values: ```typescript readonly disabled = input(false, { transform: booleanAttribute }); readonly value = input(0, { transform: numberAttribute }); ``` - **Two-Way Binding:** Model inputs enable two-way binding: ```typescript readonly value = model(0); // Creates a model input with change propagation // Model values update with .set() or .update() increment(): void { this.value.update(v => v + 1); } ``` - **Input Aliases:** Aliases provide alternative input names: ```typescript readonly value = input(0, { alias: "sliderValue" }); ``` ## 3a. Typed Reactive Forms - **Typed Forms:** Always use strictly typed reactive forms by defining an interface for the form values and using `FormGroup<MyFormType>`, `FormBuilder.group<MyFormType>()`, and `FormControl<T>()`. - **Non-Nullable Controls:** Prefer `nonNullable: true` for controls to avoid null issues and improve type safety. - **Patch and Get Values:** Use `patchValue` and `getRawValue()` to work with typed form values. - **Reference:** See the [Angular Typed Forms documentation](https://angular.dev/guide/forms/typed-forms) for details and examples. ## 4. Component Patterns - **Naming Pattern:** Components follow consistent naming - `feature.type.ts` (e.g., `hero-list.component.ts`) - **Template Extraction:** Non-trivial templates exist in separate `.html` files - **Style Extraction:** Styles exist in separate `.css/.scss` files - **Signal-Based Inputs:** Components use the `input()` function for inputs - **Two-Way Binding:** Components use the `model()` function for two-way binding - **Lifecycle Hooks:** Components implement appropriate lifecycle hook interfaces (OnInit, OnDestroy, etc.) - **Element Selectors:** Components use element selectors (`selector: 'app-hero-detail'`) - **Logic Delegation:** Services contain complex logic - **Input Initialization:** Inputs have default values or are marked as required - **Lazy Loading:** The `@defer` directive loads heavy components or features - **Error Handling:** Try-catch blocks handle errors - **Modern Control Flow:** Templates use `@if`, `@for`, `@switch` instead of structural directives - **State Representation:** Components implement loading and error states - **Derived State:** The `computed()` function calculates derived state - **No NgModules:** Do not use or reference NgModules in new code. ## 5. Styling Patterns - **Component Encapsulation:** Components use scoped styles with proper encapsulation - **CSS Methodology:** BEM methodology guides CSS class naming when not using Angular Material - **Component Libraries:** Angular Material or other component libraries provide consistent UI elements - **Theming:** Color systems and theming enable consistent visual design - **Accessibility:** Components follow a11y standards - **Dark Mode:** Components support dark mode where appropriate ## 5a. Angular Material and Angular CDK Usage - **Standard UI Library:** Use Angular Material v3 for all standard UI components (buttons, forms, navigation, dialogs, etc.) to ensure consistency, accessibility, and alignment with Angular best practices. - **Component Development:** Build new UI components and features using Angular Material components as the foundation. Only create custom components when Material does not provide a suitable solution. - **Behavioral Primitives:** Use Angular CDK for advanced behaviors (drag-and-drop, overlays, accessibility, virtual scrolling, etc.) and for building custom components that require low-level primitives. - **Theming:** Leverage Angular Material's theming system for consistent color schemes, dark mode support, and branding. Define and use custom themes in `styles.scss` or feature-level styles as needed. - **Accessibility:** All UI components must meet accessibility (a11y) standards. Prefer Material components for built-in a11y support. When using CDK or custom components, follow WCAG and ARIA guidelines. - **Best Practices:** - Prefer Material's layout and typography utilities for spacing and text. - Use Material icons and fonts for visual consistency. - Avoid mixing multiple UI libraries in the same project. - Reference the [Angular Material documentation](https://material.angular.io) for usage patterns and updates. - **CDK Utilities:** Use Angular CDK utilities for custom behaviors, overlays, accessibility, and testing harnesses. - **Migration:** For legacy or custom components, migrate to Angular Material/CDK where feasible. ## 5b. Template Patterns - **Modern Control Flow:** Use the new Angular control flow syntax: `@if`, `@for`, `@switch` in templates. Do not use legacy structural directives such as `*ngIf`, `*ngFor`, or `*ngSwitch`. - **No Legacy Structural Directives:** Remove or migrate any usage of `*ngIf`, `*ngFor`, or `*ngSwitch` to the new control flow syntax in all new code. Legacy code should be migrated when touched. - **Referencing Conditional Results:** When using `@if`, reference the result using the `as` keyword, e.g. `@if (user(); as u) { ... }`. This is the recommended pattern for accessing the value inside the block. See the [Angular documentation](https://angular.dev/guide/templates/control-flow#referencing-the-conditional-expressions-result) for details. ## 6. Service and DI Patterns - **Service Declaration:** Services use the `@Injectable()` decorator with `providedIn: 'root'` for singletons - **Data Services:** Data services handle API calls and data operations - **Error Handling:** Services include error handling - **DI Hierarchy:** Services follow the Angular DI hierarchy - **Service Contracts:** Interfaces define service contracts - **Focused Responsibilities:** Services focus on specific tasks - **Function-Based DI:** Use function-based dependency injection with the `inject()` function instead of constructor-based injection in all new code. Example: ```typescript import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; export class MyService { private readonly http = inject(HttpClient); // ... } ``` ## 7. Directive and Pipe Patterns - **Attribute Directives:** Directives handle presentation logic without templates - **Host Property:** The `host` property manages bindings and listeners: ```typescript @Directive({ selector: '[appHighlight]', host: { // Host bindings '[class.highlighted]': 'isHighlighted', '[style.color]': 'highlightColor', // Host listeners '(click)': 'onClick($event)', '(mouseenter)': 'onMouseEnter()', '(mouseleave)': 'onMouseLeave()', // Static properties 'role': 'button', '[attr.aria-label]': 'ariaLabel' } }) ``` - **Selector Prefixes:** Directive selectors use custom prefixes - **Pure Pipes:** Pipes are pure when possible for better performance - **Pipe Naming:** Pipes follow camelCase naming conventions ## 8. State Management Patterns - **Signals:** Signals serve as the primary state management solution - **Component Inputs:** Signal inputs with `input()` handle component inputs - **Two-Way Binding:** Model inputs with `model()` enable two-way binding - **Local State:** Writable signals with `signal()` manage local component state - **Derived State:** Computed signals with `computed()` calculate derived state - **Side Effects:** The `effect()` function handles side effects - **Error Handling:** Signal computations include error handling - **Signal Conversion:** The `toSignal()` and `toObservable()` functions enable interoperability with RxJS ## 9. Testing Patterns - **Test Coverage:** Tests cover components and services - **Unit Tests:** Focused unit tests verify services, pipes, and components - **Component Testing:** TestBed and component harnesses test components - **Mocking:** Tests use mocking techniques for dependencies - **Test Organization:** Tests follow the AAA pattern (Arrange, Act, Assert) - **Test Naming:** Tests have descriptive names that explain the expected behavior - **Playwright Usage:** Playwright handles E2E testing with fixtures and test isolation - **Test Environment:** Test environments match production as closely as possible ## 10. Performance Patterns - **Change Detection:** Components use OnPush change detection strategy - **Lazy Loading:** Routes and components load lazily - **Virtual Scrolling:** Virtual scrolling renders long lists efficiently - **Memoization:** Memoization optimizes expensive computations - **Bundle Size:** Bundle size monitoring and optimization reduce load times - **Server-Side Rendering:** SSR improves initial load performance - **Web Workers:** Web workers handle intensive operations ## 11. Security Patterns - **XSS Prevention:** User input undergoes sanitization - **CSRF Protection:** CSRF tokens secure forms - **Content Security Policy:** CSP headers restrict content sources - **Authentication:** Secure authentication protects user accounts - **Authorization:** Authorization checks control access - **Sensitive Data:** Client-side code excludes sensitive data ## 12. Accessibility Patterns - **ARIA Attributes:** ARIA attributes enhance accessibility - **Keyboard Navigation:** Interactive elements support keyboard access - **Color Contrast:** UI elements maintain proper color contrast ratios - **Screen Readers:** Components work with screen readers - **Focus Management:** Focus management guides user interaction - **Alternative Text:** Images include alt text
# NgRx Signals Patterns This document outlines the state management patterns used in our Angular applications with NgRx Signals Store. ## 1. NgRx Signals Architecture - **Component-Centric Design:** Stores are designed around component requirements - **Hierarchical State:** State is organized in hierarchical structures - **Computed State:** Derived state uses computed values - **Declarative Updates:** State updates use patchState for immutability - **Store Composition:** Stores compose using features and providers - **Reactivity:** UIs build on automatic change detection - **Signal Interoperability:** Signals integrate with existing RxJS-based systems - **SignalMethod & RxMethod:** Use `signalMethod` for lightweight, signal-driven side effects; use `rxMethod` for Observable-based side effects and RxJS integration. When a service returns an Observable, always use `rxMethod` for side effects instead of converting to Promise or using async/await. ## 2. Signal Store Structure - **Store Creation:** The `signalStore` function creates stores - **Protected State:** Signal Store state is protected by default (`{ protectedState: true }`) - **State Definition:** Initial state shape is defined with `withState<StateType>({...})` - Root level state is always an object: `withState({ users: [], count: 0 })` - Arrays are contained within objects: `withState({ items: [] })` - **Dependency Injection:** Stores are injectable with `{ providedIn: 'root' }` or feature/component providers - **Store Features:** Built-in features (`withEntities`, `withHooks`, `signalStoreFeature`) handle cross-cutting concerns and enable store composition - **State Interface:** State interfaces provide strong typing - **Private Members:** Prefix all internal state, computed signals, and methods with an underscore (`_`). Ensure unique member names across state, computed, and methods. ```typescript withState({ count: 0, _internalCount: 0 }); withComputed(({ count, _internalCount }) => ({ doubleCount: computed(() => count() * 2), _doubleInternal: computed(() => _internalCount() * 2), })); ``` - **Member Integrity:** Store members have unique names across state, computed, and methods - **Initialization:** State initializes with meaningful defaults - **Collection Management:** The `withEntities` feature manages collections. Prefer atomic entity operations (`addEntity`, `updateEntity`, `removeEntity`, `setAllEntities`) over bulk state updates. Use `entityConfig` and `selectId` for entity identification. - **Entity Adapter Configuration:** Use `entityConfig` to configure the entity adapter for each store. Always specify the `entity` type, `collection` name, and a `selectId` function for unique entity identification. Pass the config to `withEntities<T>(entityConfig)` for strong typing and consistent entity management. ```typescript const userEntityConfig = entityConfig({ entity: type<User>(), collection: "users", selectId: (user: User) => user.id, }); export const UserStore = signalStore( { providedIn: "root" }, withState(initialState), withEntities(userEntityConfig), // ... ); ``` - **Custom Store Properties:** Use `withProps` to add static properties, observables, and dependencies. Expose observables with `toObservable`. ```typescript // Signal store structure example import { signalStore, withState, withComputed, withMethods, patchState, type, } from "@ngrx/signals"; import { withEntities, entityConfig } from "@ngrx/signals/entities"; import { computed, inject } from "@angular/core"; import { UserService } from "./user.service"; import { User } from "./user.model"; import { setAllEntities } from "@ngrx/signals/entities"; export interface UserState { selectedUserId: string | null; loading: boolean; error: string | null; } const initialState: UserState = { selectedUserId: null, loading: false, error: null, }; const userEntityConfig = entityConfig({ entity: type<User>(), collection: "users", selectId: (user: User) => user.id, }); export const UserStore = signalStore( { providedIn: "root" }, withState(initialState), withEntities(userEntityConfig), withComputed(({ usersEntities, usersEntityMap, selectedUserId }) => ({ selectedUser: computed(() => { const id = selectedUserId(); return id ? usersEntityMap()[id] : undefined; }), totalUserCount: computed(() => usersEntities().length), })), withMethods((store, userService = inject(UserService)) => ({ loadUsers: rxMethod<void>( pipe( switchMap(() => { patchState(store, { loading: true, error: null }); return userService.getUsers().pipe( tapResponse({ next: (users) => patchState(store, setAllEntities(users, userEntityConfig), { loading: false, }), error: () => patchState(store, { loading: false, error: "Failed to load users", }), }), ); }), ), ), selectUser(userId: string | null): void { patchState(store, { selectedUserId: userId }); }, })), ); ``` ## 3. Signal Store Methods - **Method Definition:** Methods are defined within `withMethods` - **Dependency Injection:** The `inject()` function accesses services within `withMethods` - **Method Organization:** Methods are grouped by domain functionality - **Method Naming:** Methods have clear, action-oriented names - **State Updates:** `patchState(store, newStateSlice)` or `patchState(store, (currentState) => newStateSlice)` updates state immutably - **Async Operations:** Methods handle async operations and update loading/error states - **Computed Properties:** `withComputed` defines derived state - **RxJS Integration:** `rxMethod` integrates RxJS streams. Use `rxMethod` for all store methods that interact with Observable-based APIs or services. Avoid using async/await with Observables in store methods. ```typescript // Signal store method patterns import { signalStore, withState, withMethods, patchState } from "@ngrx/signals"; import { inject } from "@angular/core"; import { TodoService } from "./todo.service"; import { Todo } from "./todo.model"; export interface TodoState { todos: Todo[]; loading: boolean; } export const TodoStore = signalStore( { providedIn: "root" }, withState<TodoState>({ todos: [], loading: false }), withMethods((store, todoService = inject(TodoService)) => ({ addTodo(todo: Todo): void { patchState(store, (state) => ({ todos: [...state.todos, todo], })); }, loadTodosSimple: rxMethod<void>( pipe( switchMap(() => { patchState(store, { loading: true }); return todoService.getTodos().pipe( tapResponse({ next: (todos) => patchState(store, { todos, loading: false }), error: () => patchState(store, { loading: false }), }), ); }), ), ), })), ); ``` ## 4. Entity Management - **Entity Configuration:** Entity configurations include ID selectors - **Collection Operations:** Entity operations handle CRUD operations - **Entity Relationships:** Computed properties manage entity relationships - **Entity Updates:** Prefer atomic entity operations (`addEntity`, `updateEntity`, `removeEntity`, `setAllEntities`) over bulk state updates. Use `entityConfig` and `selectId` for entity identification. ```typescript // Entity management patterns const userEntityConfig = entityConfig({ entity: type<User>(), collection: "users", selectId: (user: User) => user.id, }); export const UserStore = signalStore( withEntities(userEntityConfig), withMethods((store) => ({ addUser: signalMethod<User>((user) => { patchState(store, addEntity(user, userEntityConfig)); }), updateUser: signalMethod<{ id: string; changes: Partial<User> }>( ({ id, changes }) => { patchState(store, updateEntity({ id, changes }, userEntityConfig)); }, ), removeUser: signalMethod<string>((id) => { patchState(store, removeEntity(id, userEntityConfig)); }), setUsers: signalMethod<User[]>((users) => { patchState(store, setAllEntities(users, userEntityConfig)); }), })), ); ``` ## 5. Component Integration ### Component State Access - **Signal Properties:** Components access signals directly in templates - **OnPush Strategy:** Signal-based components use OnPush change detection - **Store Injection:** Components inject store services with the `inject` function - **Default Values:** Signals have default values - **Computed Values:** Components derive computed values from signals - **Signal Effects:** Component effects handle side effects ```typescript // Component integration patterns @Component({ standalone: true, imports: [UserListComponent], template: ` @if (userStore.users().length > 0) { <app-user-list [users]="userStore.users()"></app-user-list> } @else { <p>No users loaded yet.</p> } <div>Selected user: {{ selectedUserName() }}</div> `, changeDetection: ChangeDetectionStrategy.OnPush, }) export class UsersContainerComponent implements OnInit { readonly userStore = inject(UserStore); selectedUserName = computed(() => { const user = this.userStore.selectedUser(); return user ? user.name : "None"; }); constructor() { effect(() => { const userId = this.userStore.selectedUserId(); if (userId) { console.log(`User selected: ${userId}`); } }); } ngOnInit() { this.userStore.loadUsers(); } } ``` ### Signal Store Hooks - **Lifecycle Hooks:** The `withHooks` feature adds lifecycle hooks to stores - **Initialization:** The `onInit` hook initializes stores - **Cleanup:** The `onDestroy` hook cleans up resources - **State Synchronization:** Hooks synchronize state between stores ```typescript // Signal store hooks patterns export const UserStore = signalStore( withState<UserState>({ /* initial state */ }), withMethods(/* store methods */), withHooks({ onInit: (store) => { // Initialize the store store.loadUsers(); // Return cleanup function if needed return () => { // Cleanup code }; }, }), ); ``` ## 6. Advanced Signal Patterns ### Signal Store Features - **Feature Creation:** The `signalStoreFeature` function creates reusable features - **Generic Feature Types:** Generic type parameters enhance feature reusability ```typescript function withMyFeature<T>(config: Config<T>) { return signalStoreFeature(/*...*/); } ``` - **Feature Composition:** Multiple features compose together - **Cross-Cutting Concerns:** Features handle logging, undo/redo, and other concerns - **State Slices:** Features define and manage specific state slices ```typescript // Signal store feature patterns export function withUserFeature() { return signalStoreFeature( withState<UserFeatureState>({ /* feature state */ }), withComputed((state) => ({ /* computed properties */ })), withMethods((store) => ({ /* methods */ })), ); } // Using the feature export const AppStore = signalStore( withUserFeature(), withOtherFeature(), withMethods((store) => ({ /* app-level methods */ })), ); ``` ### Signals and RxJS Integration - **Signal Conversion:** `toSignal()` and `toObservable()` convert between Signals and Observables - **Effects:** Angular's `effect()` function reacts to signal changes - **RxJS Method:** `rxMethod<T>(pipeline)` handles Observable-based side effects. Always prefer `rxMethod` for Observable-based service calls in stores. Do not convert Observables to Promises for store logic. - Accepts input values, Observables, or Signals - Manages subscription lifecycle automatically - **Reactive Patterns:** Signals combine with RxJS for complex asynchronous operations ```typescript // Signal and RxJS integration patterns import { signalStore, withState, withMethods, patchState } from "@ngrx/signals"; import { rxMethod } from "@ngrx/signals/rxjs-interop"; import { tapResponse } from "@ngrx/operators"; import { pipe, switchMap } from "rxjs"; import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; import { User } from "./user.model"; export interface UserState { users: User[]; loading: boolean; error: string | null; } export const UserStore = signalStore( { providedIn: "root" }, withState({ users: [], loading: false, error: null }), withMethods((store, http = inject(HttpClient)) => ({ loadUsers: rxMethod<void>( pipe( switchMap(() => { patchState(store, { loading: true, error: null }); return http.get<User[]>("/api/users").pipe( tapResponse({ next: (users) => patchState(store, { users, loading: false }), error: () => patchState(store, { loading: false, error: "Failed to load users", }), }), ); }), ), ), })), ); ``` ### Signal Method for Side Effects The `signalMethod` function manages side effects driven by Angular Signals within Signal Store: - **Input Flexibility:** The processor function accepts static values or Signals - **Automatic Cleanup:** The underlying effect cleans up when the store is destroyed - **Explicit Tracking:** Only the input signal passed to the processor function is tracked - **Lightweight:** Smaller bundle size compared to `rxMethod` ```typescript // Signal method patterns import { signalStore, withState, withMethods, patchState } from '@ngrx/signals'; import { signalMethod } from '@ngrx/signals'; import { inject } from '@angular/core'; import { Logger } from './logger'; interface UserPreferencesState { theme: 'light' | 'dark'; sendNotifications: boolean; const initialState: UserPreferencesState = { theme: 'light', sendNotifications: true, }; export const PreferencesStore = signalStore( { providedIn: 'root' }, withState(initialState), withProps(() => ({ logger: inject(Logger), })); withMethods((store) => ({ setSendNotifications(enabled: boolean): void { patchState(store, { sendNotifications: enabled }); }, // Signal method reacts to theme changes logThemeChange: signalMethod<'light' | 'dark'>((theme) => { store.logger.log(`Theme changed to: ${theme}`); }), setTheme(newTheme: 'light' | 'dark'): void { patchState(store, { theme: newTheme }); }, })), ); ``` ## 7. Custom Store Properties - **Custom Properties:** The `withProps` feature adds static properties, observables, and dependencies - **Observable Exposure:** `toObservable` within `withProps` exposes state as observables ```typescript withProps(({ isLoading }) => ({ isLoading$: toObservable(isLoading), })); ``` - **Dependency Grouping:** `withProps` groups dependencies for use across store features ```typescript withProps(() => ({ booksService: inject(BooksService), logger: inject(Logger), })); ``` ## 8. Project Organization ### Store Organization - **File Location:** Store definitions (`*.store.ts`) exist in dedicated files - **Naming Convention:** Stores follow the naming pattern `FeatureNameStore` - **Model Co-location:** State interfaces and models exist near store definitions - **Provider Functions:** Provider functions (`provideFeatureNameStore()`) encapsulate store providers ```typescript // Provider function pattern import { Provider } from "@angular/core"; import { UserStore } from "./user.store"; export function provideUserSignalStore(): Provider { return UserStore; } ``` ### Store Hierarchy - **Parent-Child Relationships:** Stores have clear relationships - **State Sharing:** Related components share state - **State Ownership:** Each state slice has a clear owner - **Store Composition:** Complex UIs compose multiple stores
# NgRx Signals Testing Guidelines These guidelines outline best practices for testing NgRx Signals Stores in Angular applications. ## 1. General Testing Patterns - **Public API Testing:** Tests interact with stores through their public API - **TestBed Usage:** Angular's `TestBed` instantiates and injects Signal Stores - **Dependency Mocking:** Tests mock store dependencies - **Store Mocking:** Component tests mock stores - **State and Computed Testing:** Tests assert on signal and computed property values - **Method Testing:** Tests trigger methods and assert on resulting state - **Protected State Access:** The `unprotected` utility from `@ngrx/signals/testing` accesses protected state - **Integration Testing:** Tests cover stores and components together - **Custom Extension Testing:** Tests verify custom store features ## 2. Example: Store Testing ```typescript import { TestBed } from "@angular/core/testing"; import { unprotected } from "@ngrx/signals/testing"; describe("CounterStore", () => { it("recomputes doubleCount on count changes", () => { const counterStore = TestBed.inject(CounterStore); patchState(unprotected(counterStore), { count: 10 }); expect(counterStore.doubleCount()).toBe(20); }); }); ``` --- Follow these patterns for all NgRx Signals Store tests. Use Jasmine, Angular’s latest APIs, and strong typing. For more, see the official NgRx Signals documentation.
# Angular Material Theming Guidelines (v3) These guidelines define how to implement, structure, and maintain themes using Angular Material v3 in this project. They are based on the official [Angular Material Theming Guide](https://material.angular.io/guide/theming) and tailored for consistency, scalability, and maintainability. --- ## 1. Theme Structure & Organization - **Central Theme File:** - Define all theme configuration in a single SCSS file (e.g., `src/theme/_theme-colors.scss`). - Import this file in `src/styles.scss`. - **No Inline Styles:** - Do not use inline styles or hardcoded colors in components. Always use theme variables. - **Feature-Level Theming:** - For feature-specific overrides, create a dedicated SCSS partial (e.g., `feature/_feature-theme.scss`) and import it in the main theme file. ## 2. Color System - **Material Color Palettes:** - Use Material color palettes (`mat-palette`) for primary, accent, and warn colors. - Define palettes for both light and dark themes. - **Custom Colors:** - Define custom palettes using `mat-palette` and reference them via theme variables. - **Surface & Background:** - Use Material surface and background tokens for backgrounds, cards, and containers. ## 3. Theme Definition & Application - **Create Themes:** - Use `mat-light-theme` and `mat-dark-theme` to define light and dark themes. - Example: ```scss $my-primary: mat-palette($mat-indigo); $my-accent: mat-palette($mat-pink, A200, A100, A400); $my-warn: mat-palette($mat-red); $my-theme: mat-light-theme( ( color: ( primary: $my-primary, accent: $my-accent, warn: $my-warn, ), ) ); ``` - **Apply Themes Globally:** - Use `@include angular-material-theme($my-theme);` in your global styles. - **Dark Mode:** - Define a dark theme and apply it using a CSS class (e.g., `.dark-theme`). - Example: ```scss .dark-theme { @include angular-material-theme($my-dark-theme); } ``` - Toggle dark mode by adding/removing the class on the root element. ## 4. Typography - **Material Typography Config:** - Use `mat-typography-config` to define custom typography. - Apply with `@include angular-material-typography($my-typography);`. - **Consistent Font Usage:** - Use theme typography variables in all components. ## 5. Component Theming - **Theming Mixins:** - Use Angular Material theming mixins for custom components. - Example: ```scss @use "@angular/material" as mat; @include mat.button-theme($my-theme); ``` - **Custom Component Themes:** - For custom components, define and use your own theming mixins that accept a theme config. ## 6. SCSS Usage & Best Practices - **@use Syntax:** - Use the `@use` rule for all Angular Material imports (not `@import`). - **No Direct Color Usage:** - Never use raw color values. Always use theme variables or palette functions. - **Variables Naming:** - Name theme variables descriptively (e.g., `$app-primary`, `$app-accent`). - **No !important:** - Avoid `!important` in theme styles. ## 7. Do's and Don'ts **Do:** - Centralize all theming logic in SCSS theme files - Use Material mixins and tokens for all component theming - Support both light and dark themes - Use CSS classes to toggle themes - Document custom palettes and typography in the theme file **Don't:** - Hardcode colors or typography in components - Use inline styles for theming - Use legacy `@import` for Material SCSS - Mix multiple theme definitions in a single file ## 8. Integration & Maintenance - **Import Order:** - Always import theme files before component styles in `styles.scss`. - **Upgrades:** - Review the [Angular Material changelog](https://github.com/angular/components/blob/main/CHANGELOG.md) for theming changes on upgrades. - **Documentation:** - Document all customizations and overrides in the theme file. --- For more details, see the [official Angular Material Theming Guide](https://material.angular.io/guide/theming).
# Angular Testing Guidelines (Jasmine + ng-mocks) These guidelines reflect Angular v19+ best practices, ng-mocks usage, and the official Angular testing guides: - [Testing services](https://angular.dev/guide/testing/services) - [Basics of testing components](https://angular.dev/guide/testing/components-basics) - [Component testing scenarios](https://angular.dev/guide/testing/components-scenarios) - [Testing attribute directives](https://angular.dev/guide/testing/attribute-directives) - [Testing pipes](https://angular.dev/guide/testing/pipes) - [Testing utility APIs](https://angular.dev/guide/testing/utility-apis) - [NgMocks Testing Components](https://ng-mocks.sudo.eu/api/MockComponent) - [NgMocks Testing Directives](https://ng-mocks.sudo.eu/api/MockDirective) - [NgMocks Testing Pipes](https://ng-mocks.sudo.eu/api/MockPipe) - [NgMocks Testing Services](https://ng-mocks.sudo.eu/api/MockService) - [NgMocks Mocking Providers](https://ng-mocks.sudo.eu/api/MockProvider) ## 1. General Patterns - Use Jasmine for all test specs (`.spec.ts`), following the AAA pattern (Arrange, Act, Assert). - Use Angular's TestBed and ComponentFixture for setup and DOM interaction. - **Services should be tested using TestBed, not ng-mocks.** - Prefer standalone components, strong typing, and feature-based file structure. - Use ng-mocks for mocking Angular dependencies (components, directives, pipes) in component/directive/pipe tests. - Use Angular's input() and model() for signal-based inputs in tests. - Use DebugElement and By for DOM queries. - Use spyOn and jasmine.createSpy for spies and mocks. - Use fakeAsync, tick, waitForAsync, and done for async code. - Use clear, descriptive test names and group related tests with describe. - **Use the latest ng-mocks APIs:** - Use `MockBuilder` for test bed setup (standalone components: `await MockBuilder(MyComponent)`) - Use `MockRender` to create the fixture (`fixture = MockRender(MyComponent)`) - Use `ngMocks.findInstance` to get the component instance with strong typing - Use `MockInstance.scope()` for test isolation if mocking services or component methods - Use `ngMocks.autoSpy('jasmine')` in your test setup to auto-spy all mocks (optional) ## 2. Service Testing Example (TestBed) Services should be tested using Angular's TestBed, not ng-mocks. Use provideHttpClientTesting for HTTP services. ```typescript import { TestBed } from "@angular/core/testing"; import { MyService } from "./my.service"; import { provideHttpClientTesting, HttpTestingController, } from "@angular/common/http/testing"; describe("MyService", () => { let service: MyService; let httpMock: HttpTestingController; beforeEach(() => { TestBed.configureTestingModule({ providers: [MyService, provideHttpClientTesting()], }); service = TestBed.inject(MyService); httpMock = TestBed.inject(HttpTestingController); }); afterEach(() => { httpMock.verify(); }); it("should be created", () => { expect(service).toBeTruthy(); }); it("should call the API", () => { service.someApiCall().subscribe(); const req = httpMock.expectOne("/api/endpoint"); expect(req.request.method).toBe("GET"); req.flush({}); }); }); ``` ## 3. Component Testing Example (ng-mocks) ```typescript import { ComponentFixture } from "@angular/core/testing"; import { MockBuilder, MockRender, ngMocks, MockInstance } from "ng-mocks"; import { MyComponent } from "./my.component"; import { MyService } from "./my.service"; import { By } from "@angular/platform-browser"; describe("MyComponent", () => { let fixture: ComponentFixture; let component: MyComponent; let serviceMock: MyService; beforeEach(async () => { await MockBuilder(MyComponent).mock(MyService); fixture = MockRender(MyComponent); component = ngMocks.findInstance(MyComponent); serviceMock = ngMocks.findInstance(MyService); }); afterEach(() => MockInstance(MyService, undefined)); it("should create", () => { expect(component).toBeTruthy(); }); it("should render input value", () => { component.value.set("test"); fixture.detectChanges(); const el = fixture.debugElement.query(By.css(".value")); expect(el.nativeElement.textContent).toContain("test"); }); it("should call service on button click", () => { spyOn(serviceMock, "doSomething").and.returnValue("done"); const btn = fixture.debugElement.query(By.css("button")); btn.triggerEventHandler("click"); fixture.detectChanges(); expect(serviceMock.doSomething).toHaveBeenCalled(); }); it("should handle async service", fakeAsync(() => { spyOn(serviceMock, "load").and.returnValue(Promise.resolve(["a"])); component.load(); tick(); fixture.detectChanges(); expect(component.items()).toEqual(["a"]); })); }); ``` ## 4. Directive Testing Example ```typescript import { TestBed, ComponentFixture } from "@angular/core/testing"; import { MockBuilder, MockRender, ngMocks } from "ng-mocks"; import { Component } from "@angular/core"; import { MyDirective } from "./my.directive"; @Component({ template: ` Test `, }) class TestHost { value = "test"; } describe("MyDirective", () => { let fixture: ComponentFixture; let host: TestHost; beforeEach(async () => { await MockBuilder(TestHost).mock(MyDirective); fixture = MockRender(TestHost); host = fixture.point.componentInstance; }); it("should apply directive", () => { fixture.detectChanges(); const dir = ngMocks.findInstance(MyDirective); expect(dir).toBeTruthy(); }); }); ``` ## 5. Pipe Testing Example ```typescript import { TestBed } from "@angular/core/testing"; import { MockBuilder } from "ng-mocks"; import { MyPipe } from "./my.pipe"; describe("MyPipe", () => { let pipe: MyPipe; beforeEach(async () => { await MockBuilder(MyPipe); pipe = TestBed.inject(MyPipe); }); it("should transform value", () => { expect(pipe.transform("abc")).toBe("expected"); }); }); ``` ## 6. Utility Patterns - Use TestHelper classes for common DOM queries and actions. - Use DebugElement and By for querying and interacting with the DOM. - Use Angular’s async helpers (fakeAsync, tick, waitForAsync) for async code. - Use ng-mocks for all dependency mocking. ## 7. Testing Standalone Components, Directives, Pipes, and Providers with ng-mocks Standalone components, directives, pipes, and providers in Angular (v14+) can be tested and their dependencies mocked using ng-mocks. By default, MockBuilder will keep the class under test and mock all its dependencies. **You do not need to explicitly call `.keep()` for the class under test.** > **Note:** Only use `.keep()` if you want to keep a dependency (e.g., a child component or pipe), not the class under test itself. ### Mocking All Imports (Shallow Test) ```typescript import { MockBuilder, MockRender, ngMocks } from "ng-mocks"; import { MyStandaloneComponent } from "./my-standalone.component"; describe("MyStandaloneComponent", () => { beforeEach(async () => { await MockBuilder(MyStandaloneComponent); // mocks all imports by default, keeps the component under test }); it("should render", () => { const fixture = MockRender(MyStandaloneComponent); const component = ngMocks.findInstance(MyStandaloneComponent); expect(component).toBeTruthy(); }); }); ``` ### Keeping Specific Imports (Deep Test) If you want to keep a specific import (e.g., a pipe or dependency component), use `.keep()`: ```typescript beforeEach(async () => { await MockBuilder(MyStandaloneComponent).keep(MyDependencyComponent); }); ``` ### Reference - See the [ng-mocks guide for standalone components](https://ng-mocks.sudo.eu/guides/component-standalone/) for more details and advanced usage. --- **Follow these patterns for all Angular tests. Use Jasmine, ng-mocks, and Angular’s latest APIs. Prefer strong typing, standalone components, and feature-based structure. For more, see the official Angular testing guides.**