Merge pull request #3633 from obsidian-tasks-group/remove-mockedFileData-singleton

test: Remove uses of a singleton in mocked Obsidian functions

Author: claremacrae

tests/Obsidian/SimulatedFile.ts

@@ -2,7 +2,6 @@ import type { CachedMetadata } from 'obsidian';
 import type { Task } from 'Task/Task';
 import { logging } from '../../src/lib/logging';
 import { FileParser } from '../../src/Obsidian/FileParser';
-import { setCurrentCacheFile } from '../__mocks__/obsidian';
 import { MockDataLoader } from '../TestingTools/MockDataLoader';
 import type { MockDataName } from './AllCacheSampleData';
 
@@ -56,7 +55,6 @@ export interface SimulatedFile {
 export function readTasksFromSimulatedFile(filename: MockDataName): Task[] {
     const testData = MockDataLoader.get(filename);
     const logger = logging.getLogger('testCache');
-    setCurrentCacheFile(testData);
     const fileParser = new FileParser(
         testData.filePath,
         testData.fileContents,

tests/Scripting/TasksFile.test.ts

@@ -4,6 +4,8 @@ import { TasksFile } from '../../src/Scripting/TasksFile';
 import { getTasksFileFromMockData, listPathAndData } from '../TestingTools/MockDataHelpers';
 import { LinkResolver } from '../../src/Task/LinkResolver';
 import type { MockDataName } from '../Obsidian/AllCacheSampleData';
+import { getAllTags, getFirstLinkpathDest, parseFrontMatterTags } from '../__mocks__/obsidian';
+import { MockDataLoader } from '../TestingTools/MockDataLoader';
 import { determineExpressionType, formatToRepresentType } from './ScriptingTestHelpers';
 
 afterEach(() => {
@@ -306,6 +308,58 @@ describe('TasksFile - reading tags', () => {
         const tasksFile = getTasksFileFromMockData(testDataName);
         expect(tasksFile.frontmatter.tags).toEqual([]);
     });
+
+    it('should be able to read all tags for any loaded SimulatedFile', () => {
+        const file1 = getTasksFileFromMockData('yaml_tags_with_one_value_on_new_line');
+        expect(getAllTags(file1.cachedMetadata)).toEqual(['#single-value-new-line', '#task']);
+
+        const file2 = getTasksFileFromMockData('yaml_tags_with_one_value_on_single_line');
+        expect(getAllTags(file2.cachedMetadata)).toEqual(['#single-value-single-line', '#task']);
+
+        // Now see if we can again find the tags in file1
+        expect(getAllTags(file1.cachedMetadata)).toEqual(['#single-value-new-line', '#task']);
+    });
+
+    it('should be able to read frontmatter tags for any loaded SimulatedFile', () => {
+        const file1 = getTasksFileFromMockData('yaml_tags_with_one_value_on_new_line');
+        expect(parseFrontMatterTags(file1.cachedMetadata.frontmatter)).toEqual(['#single-value-new-line']);
+
+        const file2 = getTasksFileFromMockData('yaml_tags_with_one_value_on_single_line');
+        expect(parseFrontMatterTags(file2.cachedMetadata.frontmatter)).toEqual(['#single-value-single-line']);
+
+        // Now see if we can again find the tags in file1
+        expect(parseFrontMatterTags(file1.cachedMetadata.frontmatter)).toEqual(['#single-value-new-line']);
+
+        const t = () => {
+            parseFrontMatterTags(file1.frontmatter);
+        };
+        expect(t).toThrow(Error);
+        expect(t).toThrowError(
+            'FrontMatterCache not found in any loaded SimulatedFile. Did you supply TasksFile.frontmatter instead of TasksFile.cachedMetadata.frontmatter?',
+        );
+    });
+
+    it('should be able to call getFirstLinkpathDest() for any loaded SimulatedFile', () => {
+        function loadMockDataAndResolveFirstLink(testDataName: MockDataName, expectedLinkSource: string) {
+            const file = getTasksFileFromMockData(testDataName);
+            const link = file.cachedMetadata.links![0];
+            expect(link.original).toMatchInlineSnapshot(expectedLinkSource);
+            const markdownPath = MockDataLoader.markdownPath(testDataName);
+            const firstLinkpathDest = getFirstLinkpathDest(link, markdownPath);
+            return { link, markdownPath, firstLinkpathDest };
+        }
+
+        const destination1 = loadMockDataAndResolveFirstLink('link_in_file_body', '"[[yaml_tags_is_empty]]"');
+        expect(destination1.firstLinkpathDest).toMatchInlineSnapshot('"Test Data/yaml_tags_is_empty.md"');
+
+        const destination2 = loadMockDataAndResolveFirstLink('link_in_heading', '"[[multiple_headings]]"');
+        expect(destination2.firstLinkpathDest).toMatchInlineSnapshot('"Test Data/multiple_headings.md"');
+
+        // Now see if we can again resolve the link from file1
+        expect(getFirstLinkpathDest(destination1.link, destination1.markdownPath)).toMatchInlineSnapshot(
+            '"Test Data/yaml_tags_is_empty.md"',
+        );
+    });
 });
 
 describe('TasksFile - properties', () => {

tests/TestingTools/MockDataHelpers.ts

@@ -1,4 +1,3 @@
-import { setCurrentCacheFile } from '../__mocks__/obsidian';
 import { TasksFile } from '../../src/Scripting/TasksFile';
 import type { SimulatedFile } from '../Obsidian/SimulatedFile';
 import type { MockDataName } from '../Obsidian/AllCacheSampleData';
@@ -27,7 +26,6 @@ import { MockDataLoader } from './MockDataLoader';
  */
 export function getTasksFileFromMockData(testDataName: MockDataName) {
     const data = MockDataLoader.get(testDataName);
-    setCurrentCacheFile(data);
     const cachedMetadata = data.cachedMetadata;
     return new TasksFile(data.filePath, cachedMetadata);
 }

tests/TestingTools/MockDataLoader.test.ts

@@ -27,4 +27,59 @@ describe('MockDataLoader', () => {
         const path = MockDataLoader.markdownPath('query_using_properties');
         expect(path).toEqual('Test Data/query_using_properties.md');
     });
+
+    it('should locate loaded SimulatedFile from its CachedMetadata', () => {
+        const data1 = MockDataLoader.get('yaml_tags_has_multiple_values');
+        const data2 = MockDataLoader.get('yaml_tags_with_two_values_on_two_lines');
+
+        expect(MockDataLoader.findCachedMetaData(data1.cachedMetadata)).toBe(data1);
+        expect(MockDataLoader.findCachedMetaData(data2.cachedMetadata)).toBe(data2);
+    });
+
+    it('should detect CachedMetadata not previously loaded, even if it is a clone of a loaded file', () => {
+        const data1 = MockDataLoader.get('one_task');
+
+        // typescript:S7784 Prefer `structuredClone(…)` over `JSON.parse(JSON.stringify(…))` to create a deep clone.
+        // But structuredClone() is not available in Jest.
+        const clonedMetadata = JSON.parse(JSON.stringify(data1.cachedMetadata)); // NOSONAR
+        expect(clonedMetadata).toStrictEqual(data1.cachedMetadata);
+        const t = () => {
+            MockDataLoader.findCachedMetaData(clonedMetadata);
+        };
+
+        expect(t).toThrow(Error);
+        expect(t).toThrowError('CachedMetadata not found in any loaded SimulatedFile');
+    });
+
+    it('should locate loaded SimulatedFile from its Frontmatter', () => {
+        const data1 = MockDataLoader.get('yaml_tags_has_multiple_values');
+        const data2 = MockDataLoader.get('yaml_tags_with_two_values_on_two_lines');
+
+        expect(MockDataLoader.findFrontmatter(data1.cachedMetadata.frontmatter)).toBe(data1);
+        expect(MockDataLoader.findFrontmatter(data2.cachedMetadata.frontmatter)).toBe(data2);
+    });
+
+    it('should detect call of findFrontmatter() with unknown Frontmatter', () => {
+        const t = () => {
+            MockDataLoader.findFrontmatter({});
+        };
+        expect(t).toThrow(Error);
+        expect(t).toThrowError('FrontMatterCache not found in any loaded SimulatedFile');
+    });
+
+    it('should locate loaded SimulatedFile from its path', () => {
+        const data1 = MockDataLoader.get('callout');
+        const data2 = MockDataLoader.get('no_yaml');
+
+        expect(MockDataLoader.findDataFromMarkdownPath('Test Data/callout.md')).toBe(data1);
+        expect(MockDataLoader.findDataFromMarkdownPath('Test Data/no_yaml.md')).toBe(data2);
+    });
+
+    it('should detect call of findDataFromMarkdownPath() with unknown path', () => {
+        const t = () => {
+            MockDataLoader.findDataFromMarkdownPath('Test Data/non-existent path.md');
+        };
+        expect(t).toThrow(Error);
+        expect(t).toThrowError('Markdown path not found in any loaded SimulatedFile');
+    });
 });

tests/TestingTools/MockDataLoader.ts

@@ -1,6 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 
+import type { CachedMetadata, FrontMatterCache } from 'obsidian';
+
 import type { SimulatedFile } from '../Obsidian/SimulatedFile';
 import type { MockDataName } from '../Obsidian/AllCacheSampleData';
 
@@ -63,4 +65,79 @@ export class MockDataLoader {
     public static markdownPath(_testDataName: MockDataName) {
         return `Test Data/${_testDataName}.md`;
     }
+
+    /**
+     * Find the {@link SimulatedFile} that contains the specified CachedMetadata.
+     *
+     * Searches through all cached {@link SimulatedFile} entries to find the one whose
+     * cachedMetadata property is identical (by reference) to the provided value.
+     *
+     * @param cachedMetadata - The CachedMetadata object to search for
+     * @returns The SimulatedFile containing the matching cachedMetadata
+     * @throws Error if no matching SimulatedFile is found in the cache
+     */
+    public static findCachedMetaData(cachedMetadata: CachedMetadata): SimulatedFile {
+        return this.findByPredicate(
+            (simulatedFile) => simulatedFile.cachedMetadata === cachedMetadata,
+            'CachedMetadata not found in any loaded SimulatedFile',
+        );
+    }
+
+    /**
+     * Find the {@link SimulatedFile} that contains the specified FrontMatterCache.
+     *
+     * Searches through all cached {@link SimulatedFile} entries to find the one whose
+     * cachedMetadata.frontmatter property is identical (by reference) to the provided value.
+     * This is useful for reverse-lookup when you have a FrontMatterCache object and need
+     * to find which file it came from.
+     *
+     * @param frontmatter - The FrontMatterCache object to search for (can be undefined)
+     * @returns The SimulatedFile containing the matching frontmatter
+     * @throws Error if no matching SimulatedFile is found in the cache
+     */
+    public static findFrontmatter(frontmatter: FrontMatterCache | undefined) {
+        return this.findByPredicate(
+            (simulatedFile) => simulatedFile.cachedMetadata.frontmatter === frontmatter,
+            'FrontMatterCache not found in any loaded SimulatedFile. Did you supply TasksFile.frontmatter instead of TasksFile.cachedMetadata.frontmatter?',
+        );
+    }
+
+    /**
+     * Find the {@link SimulatedFile} that matches the specified Markdown file path.
+     *
+     * Searches through all cached {@link SimulatedFile} entries to find the one whose
+     * filePath property exactly matches the provided Markdown path. This enables
+     * lookup of test data by the original file path from the test vault.
+     *
+     * @param markdownPath - The Markdown file path to search for (such as "Test Data/example.md")
+     * @returns The SimulatedFile with the matching file path
+     * @throws Error if no matching SimulatedFile is found in the cache
+     */
+    public static findDataFromMarkdownPath(markdownPath: string) {
+        return this.findByPredicate(
+            (simulatedFile) => simulatedFile.filePath === markdownPath,
+            'Markdown path not found in any loaded SimulatedFile',
+        );
+    }
+
+    /**
+     * Helper method to find a SimulatedFile using a custom predicate function.
+     *
+     * @param predicate - Function that returns true when the desired SimulatedFile is found
+     * @param errorMessage - Error message to throw if no matching SimulatedFile is found
+     * @returns The first SimulatedFile that matches the predicate
+     * @throws Error with the provided message if no match is found
+     */
+    private static findByPredicate(
+        predicate: (simulatedFile: SimulatedFile) => boolean,
+        errorMessage: string,
+    ): SimulatedFile {
+        for (const simulatedFile of this.cache.values()) {
+            if (predicate(simulatedFile)) {
+                return simulatedFile;
+            }
+        }
+
+        throw new Error(errorMessage);
+    }
 }

tests/TestingTools/TaskBuilder.ts

@@ -10,7 +10,6 @@ import { DateParser } from '../../src/DateTime/DateParser';
 import { StatusConfiguration, StatusType } from '../../src/Statuses/StatusConfiguration';
 import { TaskLocation } from '../../src/Task/TaskLocation';
 import { Priority } from '../../src/Task/Priority';
-import { setCurrentCacheFile } from '../__mocks__/obsidian';
 import type { ListItem } from '../../src/Task/ListItem';
 import type { SimulatedFile } from '../Obsidian/SimulatedFile';
 import type { MockDataName } from '../Obsidian/AllCacheSampleData';
@@ -79,9 +78,6 @@ export class TaskBuilder {
         if (this._tags.length > 0) {
             description += ' ' + this._tags.join(' ');
         }
-        if (this._mockData !== undefined) {
-            setCurrentCacheFile(this._mockData);
-        }
         const cachedMetadata = this._mockData?.cachedMetadata ?? {};
         const task = new Task({
             // NEW_TASK_FIELD_EDIT_REQUIRED

tests/__mocks__/obsidian.ts

@@ -1,5 +1,6 @@
 import type { App, CachedMetadata, Reference } from 'obsidian';
 import type { SimulatedFile } from '../Obsidian/SimulatedFile';
+import { MockDataLoader } from '../TestingTools/MockDataLoader';
 
 export {};
 
@@ -132,44 +133,45 @@ function caseInsensitiveSubstringSearch(searchTerm: string, phrase: string): Sea
         : null;
 }
 
-let mockedFileData: any = {};
-
-export function setCurrentCacheFile(mockData: SimulatedFile) {
-    mockedFileData = mockData;
-}
-
-function reportInconsistentTestData(functionName: string) {
-    throw new Error(
-        `Inconsistent test data used in mock ${functionName}(). Check setCurrentCacheFile() has been called with the correct {@link SimulatedFile} data.`,
-    );
-}
-
 /**
  * Fake implementation of Obsidian's `getAllTags()`.
  *
  * See https://docs.obsidian.md/Reference/TypeScript+API/getAllTags
  *
- * @param cachedMetadata
+ * @param cachedMetadata - the CachedMetadata instance from a SimulatedFile that has
+ *                         already been loaded via MockDataLoader.get().
+ * @throws Error if no matching CachedMetadata is found in the MockDataLoader cache.
  */
 export function getAllTags(cachedMetadata: CachedMetadata): string[] {
-    if (cachedMetadata !== mockedFileData.cachedMetadata) {
-        reportInconsistentTestData('getAllTags');
-    }
-    return mockedFileData.getAllTags;
+    const simulatedFile = MockDataLoader.findCachedMetaData(cachedMetadata);
+    return simulatedFile.getAllTags;
 }
 
 /**
  * Fake implementation of Obsidian's `parseFrontMatterTags()`.
  *
  * See https://docs.obsidian.md/Reference/TypeScript+API/parseFrontMatterTags
  *
- * @param frontmatter
+ * @example
+ * This works:
+ * ```typescript
+ *     const tags = parseFrontMatterTags(tasksFile.cachedMetadata.frontmatter);
+ * ```
+ *
+ * @example
+ * This does not work:
+ * ```typescript
+ *     const tags = parseFrontMatterTags(tasksFile.frontmatter);
+ * ```
+ *
+ * @param frontmatter - the raw CachedMetadata.frontmatter instance from a SimulatedFile that has
+ *                      already been loaded via MockDataLoader.get().
+ * @throws Error if no matching frontmatter is found in the MockDataLoader cache,
+ *               or a `tasksFile.frontmatter` was supplied.
  */
 export function parseFrontMatterTags(frontmatter: any | null): string[] | null {
-    if (frontmatter !== mockedFileData.cachedMetadata.frontmatter) {
-        reportInconsistentTestData('parseFrontMatterTags');
-    }
-    return mockedFileData.parseFrontMatterTags;
+    const simulatedFile = MockDataLoader.findFrontmatter(frontmatter);
+    return simulatedFile.parseFrontMatterTags;
 }
 
 /**
@@ -180,7 +182,8 @@ export function parseFrontMatterTags(frontmatter: any | null): string[] | null {
  * See https://docs.obsidian.md/Reference/TypeScript+API/MetadataCache/getFirstLinkpathDest
  *
  * @param rawLink
- * @param sourcePath
+ * @param sourcePath - the path to a Markdown file in the test vault whose SimulatedFile has already
+ *                     been loaded via MockDataLoader.get(). For example, 'Test Data/callout.md'
  *
  * @example
  * ```typescript
@@ -192,13 +195,11 @@ export function parseFrontMatterTags(frontmatter: any | null): string[] | null {
  * ```
  */
 export function getFirstLinkpathDest(rawLink: Reference, sourcePath: string): string | null {
-    if (mockedFileData.filePath !== sourcePath) {
-        reportInconsistentTestData('getFirstLinkpathDest');
-    }
-    return getFirstLinkpathDestFromData(mockedFileData, rawLink);
+    const simulatedFile = MockDataLoader.findDataFromMarkdownPath(sourcePath);
+    return getFirstLinkpathDestFromData(simulatedFile, rawLink);
 }
 
-export function getFirstLinkpathDestFromData(data: any, rawLink: Reference) {
+export function getFirstLinkpathDestFromData(data: SimulatedFile, rawLink: Reference) {
     if (!(rawLink.link in data.resolveLinkToPath)) {
         console.log(`Cannot find resolved path for ${rawLink.link} in ${data.filePath} in mock getFirstLinkpathDest()`);
     }