diff --git a/src/app/app.module.ts b/src/app/app.module.ts index 99683c1f7..b295b1723 100644 --- a/src/app/app.module.ts +++ b/src/app/app.module.ts @@ -34,7 +34,12 @@ import { CoreSiteInfoCronHandler } from '@services/handlers/site-info-cron'; import { moodleTransitionAnimation } from '@classes/page-transition'; import { TestingModule } from '@/testing/testing.module'; -// For translate loader. AoT requires an exported function for factories. +/** + * For translate loader. AoT requires an exported function for factories. + * + * @param http Http client. + * @returns Translate loader. + */ export function createTranslateLoader(http: HttpClient): TranslateHttpLoader { return new TranslateHttpLoader(http, './assets/lang/', '.json'); } diff --git a/src/core/classes/tests/database-table.test.ts b/src/core/classes/tests/database-table.test.ts index 3b9c2bca2..005bf0ff8 100644 --- a/src/core/classes/tests/database-table.test.ts +++ b/src/core/classes/tests/database-table.test.ts @@ -24,10 +24,24 @@ type User = { surname: string; }; +/** + * Checks if a user object matches specified conditions. + * + * @param user The user object to be checked. + * @param conditions The conditions to match against the user object. + * @returns Returns true if the user matches the conditions, false otherwise. + */ function userMatches(user: User, conditions: Partial) { return !Object.entries(conditions).some(([column, value]) => user[column] !== value); } +/** + * Prepares stubs for testing with a mock database configuration. + * + * @param config The partial CoreDatabaseConfiguration to use for the mock database. + * @returns An array containing a mock user records array, a mock SQLite database, + * and a CoreDatabaseTable instance for the 'users' table. + */ function prepareStubs(config: Partial = {}): [User[], SQLiteDB, CoreDatabaseTable] { const records: User[] = []; const database = mock({ @@ -68,6 +82,12 @@ function prepareStubs(config: Partial = {}): [User[], return [records, database, table]; } +/** + * Test function for finding items in the database. + * + * @param records An array of user records to use for testing. + * @param table The CoreDatabaseTable instance to test. + */ async function testFindItems(records: User[], table: CoreDatabaseTable) { const john = { id: 1, name: 'John', surname: 'Doe' }; const amy = { id: 2, name: 'Amy', surname: 'Doe' }; @@ -83,6 +103,13 @@ async function testFindItems(records: User[], table: CoreDatabaseTable) { await expect(table.getOneByPrimaryKey({ id: 2 })).resolves.toEqual(amy); } +/** + * Tests the insertion of items into a database table. + * + * @param records An array of User records. + * @param database The SQLite database instance. + * @param table The database table instance. + */ async function testInsertItems(records: User[], database: SQLiteDB, table: CoreDatabaseTable) { // Arrange. const john = { id: 1, name: 'John', surname: 'Doe' }; @@ -98,6 +125,13 @@ async function testInsertItems(records: User[], database: SQLiteDB, table: CoreD await expect(table.getOneByPrimaryKey({ id: 1 })).resolves.toEqual(john); } +/** + * Tests the deletion of items from a database table based on a condition. + * + * @param records An array of User records. + * @param database The SQLite database instance. + * @param table The database table instance. + */ async function testDeleteItems(records: User[], database: SQLiteDB, table: CoreDatabaseTable) { // Arrange. const john = { id: 1, name: 'John', surname: 'Doe' }; @@ -121,6 +155,13 @@ async function testDeleteItems(records: User[], database: SQLiteDB, table: CoreD await expect(table.getOneByPrimaryKey({ id: 3 })).resolves.toEqual(jane); } +/** + * Tests the deletion of items from a database table based on primary key values. + * + * @param records An array of User records. + * @param database The SQLite database instance. + * @param table The database table instance. + */ async function testDeleteItemsByPrimaryKey(records: User[], database: SQLiteDB, table: CoreDatabaseTable) { // Arrange. const john = { id: 1, name: 'John', surname: 'Doe' }; diff --git a/src/core/features/editor/components/rich-text-editor/rich-text-editor.ts b/src/core/features/editor/components/rich-text-editor/rich-text-editor.ts index 74bf1f1f5..990abdb66 100644 --- a/src/core/features/editor/components/rich-text-editor/rich-text-editor.ts +++ b/src/core/features/editor/components/rich-text-editor/rich-text-editor.ts @@ -656,8 +656,8 @@ export class CoreEditorRichTextEditorComponent implements OnInit, AfterViewInit, /** * Replace tags for a11y. * - * @param originTag Origin tags to be replaced. - * @param destinationTag Destination tags to replace. + * @param originTags Origin tags to be replaced. + * @param destinationTags Destination tags to replace. */ protected replaceTags(originTags: string[], destinationTags: string[]): void { if (!this.editorElement) { diff --git a/src/core/initializers/clear-tmp-folder.ts b/src/core/initializers/clear-tmp-folder.ts index 6249f79a4..44c3e2d82 100644 --- a/src/core/initializers/clear-tmp-folder.ts +++ b/src/core/initializers/clear-tmp-folder.ts @@ -14,6 +14,9 @@ import { CoreFile } from '@services/file'; +/** + * Clears the temporary folder. + */ export default async function(): Promise { await CoreFile.clearTmpFolder(); } diff --git a/src/core/initializers/consume-storage-redirect.ts b/src/core/initializers/consume-storage-redirect.ts index 990636a0c..20b776ae3 100644 --- a/src/core/initializers/consume-storage-redirect.ts +++ b/src/core/initializers/consume-storage-redirect.ts @@ -15,6 +15,9 @@ import { CoreApp } from '@services/app'; import { CoreUpdateManager } from '@services/update-manager'; +/** + * Read redirect data from local storage and clear it if it existed. + */ export default async function(): Promise { await CoreUpdateManager.donePromise; diff --git a/src/core/initializers/index.ts b/src/core/initializers/index.ts index 56c30b171..993ba5d32 100644 --- a/src/core/initializers/index.ts +++ b/src/core/initializers/index.ts @@ -14,6 +14,12 @@ import { APP_INITIALIZER, Provider } from '@angular/core'; +/** + * Get the providers for the initializers. + * Please use the APP_INITIALIZER token to provide the initializers. + * + * @returns List of providers. + */ export function getInitializerProviders(): Provider[] { const context = require.context('./', false, /\.ts$/); diff --git a/src/core/initializers/initialize-services.ts b/src/core/initializers/initialize-services.ts index 77d7b4ae8..bffdd03e0 100644 --- a/src/core/initializers/initialize-services.ts +++ b/src/core/initializers/initialize-services.ts @@ -22,6 +22,9 @@ import { CoreSites } from '@services/sites'; import { CoreUpdateManager } from '@services/update-manager'; import { CoreTimeUtils } from '@services/utils/time'; +/** + * Initializes various core components asynchronously. + */ export default async function(): Promise { await Promise.all([ CoreConfig.initialize(), diff --git a/src/core/initializers/initialize-urlscheme.ts b/src/core/initializers/initialize-urlscheme.ts index af0aee7dd..312d53c1f 100644 --- a/src/core/initializers/initialize-urlscheme.ts +++ b/src/core/initializers/initialize-urlscheme.ts @@ -16,6 +16,9 @@ import { CoreCustomURLSchemes } from '@services/urlschemes'; import { NgZone } from '@singletons'; import { CoreEvents } from '@singletons/events'; +/** + * Asynchronous function to handle custom URLs when the app is launched. + */ export default async function(): Promise { const lastUrls: Record = {}; diff --git a/src/core/initializers/initialize-user-agent.ts b/src/core/initializers/initialize-user-agent.ts index 2b87862be..3a6ab0852 100644 --- a/src/core/initializers/initialize-user-agent.ts +++ b/src/core/initializers/initialize-user-agent.ts @@ -15,6 +15,9 @@ import { CorePlatform } from '@services/platform'; import { NativeHttp } from '@singletons'; +/** + * This function sets the User-Agent header using NativeHttp for mobile platform. + */ export default async function(): Promise { if (!CorePlatform.isMobile()) { return; diff --git a/src/core/initializers/override-window-open.ts b/src/core/initializers/override-window-open.ts index 04e4ec995..d48dc9436 100644 --- a/src/core/initializers/override-window-open.ts +++ b/src/core/initializers/override-window-open.ts @@ -14,7 +14,10 @@ import { CorePlatform } from '@services/platform'; -export default async function(): Promise { +/** + * Initializes the application and sets up the InAppBrowser if available. + */ +export default async function initializeApp(): Promise { await CorePlatform.ready(); if (!window.cordova?.InAppBrowser) { diff --git a/src/core/initializers/prepare-devtools.ts b/src/core/initializers/prepare-devtools.ts index 7e0d4d255..f2442ebad 100644 --- a/src/core/initializers/prepare-devtools.ts +++ b/src/core/initializers/prepare-devtools.ts @@ -29,6 +29,11 @@ type DevelopmentWindow = Window & { pushNotifications?: CorePushNotificationsProvider; }; +/** + * Initializes the development window with necessary providers and configurations. + * + * @param window The development window object to be initialized. + */ function initializeDevelopmentWindow(window: DevelopmentWindow) { window.browser = CoreBrowser; window.appProvider = CoreApp.instance; @@ -38,6 +43,9 @@ function initializeDevelopmentWindow(window: DevelopmentWindow) { window.pushNotifications = CorePushNotifications.instance; } +/** + * Initializes the development tools if enabled by CoreConstants. + */ export default function(): void { if (!CoreConstants.enableDevTools()) { return; diff --git a/src/core/initializers/restore-session.ts b/src/core/initializers/restore-session.ts index 41914ea02..d96b32927 100644 --- a/src/core/initializers/restore-session.ts +++ b/src/core/initializers/restore-session.ts @@ -15,6 +15,9 @@ import { CoreSites } from '@services/sites'; import { CoreUpdateManager } from '@services/update-manager'; +/** + * Restores the session to the previous one so the user doesn't has to login everytime the app is started. + */ export default async function(): Promise { await CoreUpdateManager.donePromise; diff --git a/src/core/initializers/subscribe-to-keyboard-events.ts b/src/core/initializers/subscribe-to-keyboard-events.ts index 9bb7deb14..56728d493 100644 --- a/src/core/initializers/subscribe-to-keyboard-events.ts +++ b/src/core/initializers/subscribe-to-keyboard-events.ts @@ -15,6 +15,9 @@ import { CoreApp } from '@services/app'; import { NgZone, Keyboard } from '@singletons'; +/** + * Initializes keyboard event listeners and ensures Angular zone is properly managed for change detection. + */ export default function(): void { const zone = NgZone.instance; const app = CoreApp.instance; diff --git a/src/core/initializers/wait-for-platform-ready.ts b/src/core/initializers/wait-for-platform-ready.ts index 7604edb5a..90e521685 100644 --- a/src/core/initializers/wait-for-platform-ready.ts +++ b/src/core/initializers/wait-for-platform-ready.ts @@ -14,6 +14,9 @@ import { CorePlatform } from '@services/platform'; +/** + * Initializes the application when the CorePlatform is ready. + */ export default async function(): Promise { await CorePlatform.ready(); } diff --git a/src/core/initializers/watch-screen-status.ts b/src/core/initializers/watch-screen-status.ts index ee4d5fcf1..326cced43 100644 --- a/src/core/initializers/watch-screen-status.ts +++ b/src/core/initializers/watch-screen-status.ts @@ -14,6 +14,10 @@ import { CoreScreen } from '@services/screen'; +/** + * Initializes the application by watching the viewport and orientation changes. + * This function should be called to set up necessary event listeners for proper functionality. + */ export default function(): void { CoreScreen.watchViewport(); diff --git a/src/core/utils/rxjs.ts b/src/core/utils/rxjs.ts index bc29138e6..63b959856 100644 --- a/src/core/utils/rxjs.ts +++ b/src/core/utils/rxjs.ts @@ -77,6 +77,8 @@ export function asyncObservable(createObservable: () => Promise }); } +export function ignoreErrors(observable: Observable): Observable; +export function ignoreErrors(observable: Observable, fallback: Fallback): Observable; /** * Ignore errors from an observable, returning a certain value instead. * @@ -84,8 +86,6 @@ export function asyncObservable(createObservable: () => Promise * @param fallback Value to return if the observer errors. * @returns Observable with ignored errors, returning the fallback result if provided. */ -export function ignoreErrors(observable: Observable): Observable; -export function ignoreErrors(observable: Observable, fallback: Fallback): Observable; export function ignoreErrors( observable: Observable, fallback?: Fallback, diff --git a/src/testing/testing.module.ts b/src/testing/testing.module.ts index 479df360d..3b92ac120 100644 --- a/src/testing/testing.module.ts +++ b/src/testing/testing.module.ts @@ -21,6 +21,11 @@ type AutomatedTestsWindow = Window & { behat?: TestingBehatRuntimeService; }; +/** + * Initialize automated tests. + * + * @param window Window. + */ function initializeAutomatedTests(window: AutomatedTestsWindow) { if (!CoreAppProvider.isAutomated()) { return; diff --git a/src/testing/utils.ts b/src/testing/utils.ts index 092adaf13..7c78b93d8 100644 --- a/src/testing/utils.ts +++ b/src/testing/utils.ts @@ -80,6 +80,13 @@ const DEFAULT_SERVICE_SINGLETON_MOCKS: [CoreSingletonProxy, unknown][] = [ })], ]; +/** + * Renders an Angular component for testing. + * + * @param component The Angular component to render. + * @param config Configuration options for rendering. + * @returns A promise that resolves to the testing component fixture. + */ async function renderAngularComponent(component: Type, config: RenderConfig): Promise> { config.declarations.push(component); @@ -114,6 +121,13 @@ async function renderAngularComponent(component: Type, config: RenderConfi return fixture; } +/** + * Creates a wrapper component for testing. + * + * @param template The template for the wrapper component. + * @param componentClass The class of the component to be wrapped. + * @returns The wrapper component class. + */ function createWrapperComponent(template: string, componentClass: Type): Type> { @Component({ template }) class HostComponent extends WrapperComponent { @@ -125,6 +139,11 @@ function createWrapperComponent(template: string, componentClass: Type): T return HostComponent; } +/** + * Gets the default declarations for testing. + * + * @returns An array of default declarations. + */ function getDefaultDeclarations(): unknown[] { return [ TranslatePipeStub, @@ -132,6 +151,12 @@ function getDefaultDeclarations(): unknown[] { ]; } +/** + * Gets the default providers for testing. + * + * @param config Configuration options for rendering. + * @returns An array of default providers. + */ function getDefaultProviders(config: RenderConfig): unknown[] { const serviceProviders = DEFAULT_SERVICE_SINGLETON_MOCKS.map( ([singleton, mockInstance]) => ({ @@ -159,6 +184,12 @@ function getDefaultProviders(config: RenderConfig): unknown[] { ]; } +/** + * Resolves a service instance from the TestBed. + * + * @param injectionToken The injection token for the service. + * @returns The service instance or null if not found. + */ function resolveServiceInstanceFromTestBed(injectionToken: Exclude): Record | null { if (!testBedInitialized) { return null; @@ -167,6 +198,12 @@ function resolveServiceInstanceFromTestBed(injectionToken: Exclude | null; } +/** + * Creates a new instance of a service. + * + * @param injectionToken The injection token for the service. + * @returns The new service instance or null if an error occurs. + */ function createNewServiceInstance(injectionToken: Exclude): Record | null { try { const constructor = injectionToken as { new (): Record }; @@ -192,6 +229,14 @@ export type TestingComponentFixture = Omit, 'na export type WrapperComponentFixture = TestingComponentFixture>; +/** + * Finds an element in the fixture's native element. + * + * @param fixture The testing component fixture. + * @param selector The CSS selector for the element. + * @param content The text content or regular expression to match. + * @returns The element or null if not found. + */ export function findElement( fixture: TestingComponentFixture, selector: string, @@ -215,6 +260,14 @@ export function findElement( return null; } +/** + * Requires an element in the fixture's native element. + * + * @param fixture The testing component fixture. + * @param selector The CSS selector for the element. + * @param content The text content or regular expression to match. + * @returns The element. + */ export function requireElement( fixture: TestingComponentFixture, selector: string, @@ -272,6 +325,15 @@ export function mockSingleton( methods: string[], instance?: Record, ): T; + +/** + * Mocks a singleton instance for testing purposes. + * + * @param singleton The singleton class or proxy. + * @param methodsOrProperties An array of method names to mock or an object containing property names and values. + * @param properties If `methodsOrProperties` is an array, this object contains the properties to mock. + * @returns The mocked singleton instance. + */ export function mockSingleton( singleton: CoreSingletonProxy, methodsOrProperties: string[] | Record = [], @@ -299,6 +361,10 @@ export function mockSingleton( return mockInstance; } +/** + * Resets the testing environment by marking the test bed as uninitialized and + * restoring default service singleton mocks. + */ export function resetTestingEnvironment(): void { testBedInitialized = false; @@ -307,6 +373,15 @@ export function resetTestingEnvironment(): void { } } +/** + * Retrieves the service instance corresponding to the provided injection token. + * If the injection token is a string, an empty object is returned. + * If the service instance is found in the test bed, it is returned. + * If not found, a new service instance is created, or an empty object is returned if creation fails. + * + * @param injectionToken The injection token for the desired service. + * @returns The service instance or an empty object. + */ export function getServiceInstance(injectionToken: ServiceInjectionToken): Record { if (typeof injectionToken === 'string') { return {}; @@ -317,6 +392,13 @@ export function getServiceInstance(injectionToken: ServiceInjectionToken): Recor ?? {}; } +/** + * Renders a component with the given configuration. + * + * @param component The Angular component to render. + * @param config Configuration options for rendering. + * @returns A promise that resolves to the testing component fixture. + */ export async function renderComponent( component: Type, config: Partial = {}, @@ -329,6 +411,13 @@ export async function renderComponent( }); } +/** + * Renders a page component with the given configuration. + * + * @param component The Angular component to render. + * @param config Configuration options for rendering a page component. + * @returns A promise that resolves to the testing component fixture. + */ export async function renderPageComponent( component: Type, config: Partial = {}, @@ -347,6 +436,14 @@ export async function renderPageComponent( return renderComponent(component, config); } +/** + * Renders a template with the given configuration. + * + * @param component The Angular component to wrap in a template. + * @param template The template for the wrapper component. + * @param config Configuration options for rendering. + * @returns A promise that resolves to the wrapper component fixture. + */ export async function renderTemplate( component: Type, template: string, @@ -366,6 +463,15 @@ export async function renderTemplate( ); } +/** + * Renders a wrapper component with the given configuration. + * + * @param component The Angular component to wrap. + * @param tag The HTML tag for the wrapper component. + * @param inputs Input attributes for the wrapper component. + * @param config Configuration options for rendering. + * @returns A promise that resolves to the wrapper component fixture. + */ export async function renderWrapperComponent( component: Type, tag: string, @@ -423,10 +529,21 @@ export function mockTranslate(translations: Record = {}): void { }); } +/** + * Creates a test function that asserts that two types are equal. + * + * @param equal The equality check function for types A and B. + * @returns A test function that asserts equality. + */ export function expectSameTypes(equal: Equal): () => void { return () => expect(equal).toBe(true); } +/** + * Creates a test function that always asserts true, used for testing generic types. + * + * @returns A test function that always asserts true. + */ // eslint-disable-next-line @typescript-eslint/no-unused-vars export function expectAnyType(): () => void { return () => expect(true).toBe(true);