Merge pull request #3655 from obsidian-tasks-group/contrib-mock-date-examples

contrib: Add some examples of using SimulatedFile

Author: claremacrae

contributing/Testing/Using Obsidian API in tests.md

@@ -19,6 +19,87 @@ So we need a way to access Obsidian-generated data in our tests. This page tries
     - `MockDataName` in [AllCacheSampleData.ts](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/tests/Obsidian/AllCacheSampleData.ts) shows the names of all the available files, in a type-safe way.
 4. See all the [uses of this data so far, in Tasks tests](https://github.com/search?type=code&q=repo%3Aobsidian-tasks-group%2Fobsidian-tasks+%2F%28AllMockDataNames%7Cbuilder.mockData%7CgetMockDataAndReadTasks%7ClistPathAndData%7CMockDataLoader%7CMockDataName%7CreadTasksFromSimulatedFile%7CSimulatedFile%29%2F).
 
+## Examples
+
+- Test data: [as markdown files](https://github.com/obsidian-tasks-group/obsidian-tasks/tree/main/resources/sample_vaults/Tasks-Demo/Test%20Data)
+- Test data: [as json files](https://github.com/obsidian-tasks-group/obsidian-tasks/tree/main/tests/Obsidian/__test_data__)
+
+### Using Obsidian's data about an individual test Markdown file
+
+Example of the lowest-level usage, returning a [SimulatedFile](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/tests/Obsidian/SimulatedFile.ts) object:
+
+<!-- snippet: MockDataLoader.get -->
+```ts
+const data1 = MockDataLoader.get('one_task');
+```
+<!-- endSnippet -->
+
+Create a `TasksFile` object for one of the Markdown files, for writing tests:
+
+<!-- snippet: getTasksFileFromMockData -->
+```ts
+const tasksFile = getTasksFileFromMockData('no_yaml');
+```
+<!-- endSnippet -->
+
+Obtain all the `Task` objects from one of the Markdown files:
+
+<!-- snippet: readTasksFromSimulatedFile -->
+```ts
+const tasks = readTasksFromSimulatedFile('multiple_headings');
+```
+<!-- endSnippet -->
+
+Obtain both a `TasksFile` object for one of the Markdown files, and the corresponding `Task` objects:
+
+<!-- snippet: getMockDataAndReadTasks -->
+```ts
+const { data, tasks } = getMockDataAndReadTasks('callout_labelled');
+```
+<!-- endSnippet -->
+
+### Using Obsidian's data about some or all the test Markdown files
+
+Obtain all the `Task` objects from all the Markdown files:
+
+<!-- snippet: readAllTasksFromAllSimulatedFiles -->
+```ts
+const allTasks = readAllTasksFromAllSimulatedFiles();
+```
+<!-- endSnippet -->
+
+Iterate over all the Markdown files:
+
+<!-- snippet: AllMockDataNames -->
+```ts
+let output = '';
+AllMockDataNames.forEach((file) => {
+    const tasksFile = getTasksFileFromMockData(file);
+    output += visualiseLinks(tasksFile.outlinksInProperties, file);
+});
+verifyMarkdown(output);
+```
+<!-- endSnippet -->
+
+Selectively iterate over data from several of the Markdown files - using `listPathAndData()` to include each test file's `path` in the test name:
+
+<!-- snippet: iterate-over-multiple-SimulatedFiles -->
+```ts
+it.each(
+    listPathAndData([
+        'yaml_custom_number_property', // no tags value in frontmatter
+        'yaml_tags_field_added_by_obsidian_but_not_populated',
+        'yaml_tags_had_value_then_was_emptied_by_obsidian',
+        'yaml_tags_is_empty_list',
+        'yaml_tags_is_empty',
+    ]),
+)('should provide empty list if no tags in frontmatter: "%s"', (_path: string, testDataName: MockDataName) => {
+    const tasksFile = getTasksFileFromMockData(testDataName);
+    expect(tasksFile.frontmatter.tags).toEqual([]);
+});
+```
+<!-- endSnippet -->
+
 ## Test data creation sequence
 
 If using this on an Obsidian version newer than the one in saved `tests/Obsidian/__test_data__/*.json`, go to Settings → Files and links → Advanced → Rebuild vault cache.

resources/sample_vaults/Tasks-Demo/_meta/templater_scripts/convert_test_data_markdown_to_js.js

@@ -135,19 +135,27 @@ export type MockDataName =
 
 /**
  * Names of all the sample data in \`resources/sample_vaults/Tasks-Demo/Test Data\`.
+ *
+ * To read all the tasks in all the sample data files,
+ * use {@link readAllTasksFromAllSimulatedFiles}
+ *
  * Example use:
  *
  * \`\`\`typescript
- *      const tasks: Task[] = AllMockDataNames.flatMap((testDataName) => {
- *          return readTasksFromSimulatedFile(testDataName);
+ *      let output = '';
+ *      AllMockDataNames.forEach((file) => {
+ *          const tasksFile = getTasksFileFromMockData(file);
+ *          output += visualiseLinks(tasksFile.outlinksInProperties, file);
  *      });
+ *      verifyMarkdown(output);
  * \`\`\`
  *
  * Related code that uses some or all of this data:
  * - {@link SimulatedFile}
  * - {@link readTasksFromSimulatedFile}
  * - {@link getTasksFileFromMockData}
  * - {@link listPathAndData}
+ * - {@link readAllTasksFromAllSimulatedFiles}
  */
 export const AllMockDataNames: MockDataName[] = [
     '${basenames.join("',\n    '")}',

tests/Obsidian/AllCacheSampleData.ts

@@ -93,19 +93,27 @@ export type MockDataName =
 
 /**
  * Names of all the sample data in `resources/sample_vaults/Tasks-Demo/Test Data`.
+ *
+ * To read all the tasks in all the sample data files,
+ * use {@link readAllTasksFromAllSimulatedFiles}
+ *
  * Example use:
  *
  * ```typescript
- *      const tasks: Task[] = AllMockDataNames.flatMap((testDataName) => {
- *          return readTasksFromSimulatedFile(testDataName);
+ *      let output = '';
+ *      AllMockDataNames.forEach((file) => {
+ *          const tasksFile = getTasksFileFromMockData(file);
+ *          output += visualiseLinks(tasksFile.outlinksInProperties, file);
  *      });
+ *      verifyMarkdown(output);
  * ```
  *
  * Related code that uses some or all of this data:
  * - {@link SimulatedFile}
  * - {@link readTasksFromSimulatedFile}
  * - {@link getTasksFileFromMockData}
  * - {@link listPathAndData}
+ * - {@link readAllTasksFromAllSimulatedFiles}
  */
 export const AllMockDataNames: MockDataName[] = [
     'all_link_types',

tests/Obsidian/Cache.test.ts

@@ -633,7 +633,9 @@ describe('cache', () => {
     });
 
     it('callout_labelled', () => {
+        // begin-snippet: getMockDataAndReadTasks
         const { data, tasks } = getMockDataAndReadTasks('callout_labelled');
+        // end-snippet
         expect(data.fileContents).toMatchInlineSnapshot(`
             "# callout_labelled
 

tests/Obsidian/FileParser.test.ts

@@ -7,7 +7,9 @@ describe('FileParser', () => {
         // I found that intentionally breaking the setting of _sectionIndex was
         // not caught by any other tests.
 
+        // begin-snippet: readTasksFromSimulatedFile
         const tasks = readTasksFromSimulatedFile('multiple_headings');
+        // end-snippet
         const locationDataExceptTasksFile = tasks.map((task) => task.taskLocation.allFieldsExceptTasksFileForTesting());
         expect(locationDataExceptTasksFile).toMatchInlineSnapshot(`
             [

tests/Obsidian/SimulatedFile.ts

@@ -3,7 +3,7 @@ import type { Task } from 'Task/Task';
 import { logging } from '../../src/lib/logging';
 import { FileParser } from '../../src/Obsidian/FileParser';
 import { MockDataLoader } from '../TestingTools/MockDataLoader';
-import type { MockDataName } from './AllCacheSampleData';
+import { AllMockDataNames, type MockDataName } from './AllCacheSampleData';
 
 /**
  * @file This file provides functions for creating {@link Task} objects from data in `tests/Obsidian/__test_data__`.
@@ -51,6 +51,7 @@ export interface SimulatedFile {
  * ```
  *
  * For more info, see https://publish.obsidian.md/tasks-contributing/Testing/Using+Obsidian+API+in+tests.
+ * @see readAllTasksFromAllSimulatedFiles
  */
 export function readTasksFromSimulatedFile(filename: MockDataName): Task[] {
     const testData = MockDataLoader.get(filename);
@@ -66,6 +67,18 @@ export function readTasksFromSimulatedFile(filename: MockDataName): Task[] {
     return fileParser.parseFileContent();
 }
 
+/**
+ * Read all tasks from Obsidian-specific data read from all JSON files in `tests/Obsidian/__test_data__`.
+ *
+ * For more info, see https://publish.obsidian.md/tasks-contributing/Testing/Using+Obsidian+API+in+tests.
+ * @see readTasksFromSimulatedFile
+ */
+export function readAllTasksFromAllSimulatedFiles() {
+    return AllMockDataNames.flatMap((testDataName) => {
+        return readTasksFromSimulatedFile(testDataName);
+    });
+}
+
 function errorReporter() {
     return;
 }

tests/Scripting/ScriptingReference/CustomFiltering/CustomFilteringExamples.test.ts

@@ -4,8 +4,7 @@
 
 import moment from 'moment';
 import type { Task } from '../../../../src/Task/Task';
-import { AllMockDataNames } from '../../../Obsidian/AllCacheSampleData';
-import { readTasksFromSimulatedFile } from '../../../Obsidian/SimulatedFile';
+import { readAllTasksFromAllSimulatedFiles } from '../../../Obsidian/SimulatedFile';
 import { fromLine, fromLines } from '../../../TestingTools/TestHelpers';
 import { SampleTasks } from '../../../TestingTools/SampleTasks';
 import type { CustomPropertyDocsTestData, QueryInstructionLineAndDescription } from '../VerifyFunctionFieldSamples';
@@ -357,9 +356,9 @@ describe('file properties', () => {
 });
 
 describe('obsidian properties', () => {
-    const tasks: Task[] = AllMockDataNames.flatMap((testDataName) => {
-        return readTasksFromSimulatedFile(testDataName);
-    });
+    // begin-snippet: readAllTasksFromAllSimulatedFiles
+    const allTasks = readAllTasksFromAllSimulatedFiles();
+    // end-snippet
 
     const testData: CustomPropertyDocsTestData[] = [
         // ---------------------------------------------------------------------------------
@@ -386,7 +385,7 @@ describe('obsidian properties', () => {
                     "find tasks in files where the date property 'creation date' includes string '2024'",
                 ],
             ],
-            tasks,
+            allTasks,
         ],
     ];
 

tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.ts

@@ -5,8 +5,7 @@
 import moment from 'moment';
 
 import type { Task } from '../../../../src/Task/Task';
-import { AllMockDataNames } from '../../../Obsidian/AllCacheSampleData';
-import { readTasksFromSimulatedFile } from '../../../Obsidian/SimulatedFile';
+import { readAllTasksFromAllSimulatedFiles } from '../../../Obsidian/SimulatedFile';
 import { SampleTasks } from '../../../TestingTools/SampleTasks';
 import {
     type CustomPropertyDocsTestData,
@@ -380,9 +379,7 @@ describe('file properties', () => {
 });
 
 describe('obsidian properties', () => {
-    const tasks: Task[] = AllMockDataNames.flatMap((testDataName) => {
-        return readTasksFromSimulatedFile(testDataName);
-    });
+    const tasks = readAllTasksFromAllSimulatedFiles();
 
     const testData: CustomPropertyDocsTestData[] = [
         // ---------------------------------------------------------------------------------

tests/Scripting/TasksFile.test.ts

@@ -296,6 +296,7 @@ describe('TasksFile - reading tags', () => {
         expect(tasksFile.tags).toEqual(['#task']);
     });
 
+    // begin-snippet: iterate-over-multiple-SimulatedFiles
     it.each(
         listPathAndData([
             'yaml_custom_number_property', // no tags value in frontmatter
@@ -308,6 +309,7 @@ describe('TasksFile - reading tags', () => {
         const tasksFile = getTasksFileFromMockData(testDataName);
         expect(tasksFile.frontmatter.tags).toEqual([]);
     });
+    // end-snippet
 
     it('should be able to read all tags for any loaded SimulatedFile', () => {
         const file1 = getTasksFileFromMockData('yaml_tags_with_one_value_on_new_line');
@@ -384,7 +386,9 @@ describe('TasksFile - properties', () => {
     });
 
     it('should treat non-exising properties correctly', () => {
+        // begin-snippet: getTasksFileFromMockData
         const tasksFile = getTasksFileFromMockData('no_yaml');
+        // end-snippet
         expect(tasksFile.hasProperty('appleSauce')).toEqual(false);
     });
 

tests/Task/Link.test.ts

@@ -344,12 +344,14 @@ describe('visualise links', () => {
     });
 
     it('properties', () => {
+        // begin-snippet: AllMockDataNames
         let output = '';
         AllMockDataNames.forEach((file) => {
             const tasksFile = getTasksFileFromMockData(file);
             output += visualiseLinks(tasksFile.outlinksInProperties, file);
         });
         verifyMarkdown(output);
+        // end-snippet
     });
 
     it('outlinks', () => {