Merge branch 'master' into dependabot/github_actions/actions/checkout-4

Author: ozyx

API.md

@@ -590,35 +590,108 @@ MinMax queries are issued by plots, and may be issued by other types as well.  T
 #### Telemetry Formats
 
 Telemetry format objects define how to interpret and display telemetry data.
-They have a simple structure:
-
-- `key`: A `string` that uniquely identifies this formatter.
-- `format`: A `function` that takes a raw telemetry value, and returns a
-  human-readable `string` representation of that value. It has one required
-  argument, and three optional arguments that provide context and can be used
-  for returning scaled representations of a value. An example of this is
-  representing time values in a scale such as the time conductor scale. There
-  are multiple ways of representing a point in time, and by providing a minimum
-  scale value, maximum scale value, and a count, it's possible to provide more
-  useful representations of time given the provided limitations.  
-  - `value`: The raw telemetry value in its native type.
-  - `minValue`: An **optional** argument specifying the minimum displayed
-      value.
-  - `maxValue`: An **optional** argument specifying the maximum displayed
-      value.
-  - `count`: An **optional** argument specifying the number of displayed
-      values.
-- `parse`: A `function` that takes a `string` representation of a telemetry
-  value, and returns the value in its native type. **Note** parse might receive an already-parsed value.  This function should be idempotent.
-- `validate`: A `function` that takes a `string` representation of a telemetry
-  value, and returns a `boolean` value indicating whether the provided string
-  can be parsed.
+They have a simple structure, provided here as a TypeScript interface:
+
+```ts
+interface Formatter {
+    key: string; // A string that uniquely identifies this formatter.
+
+    format: (
+        value: any, // The raw telemetry value in its native type.
+        minValue?: number, // An optional argument specifying the minimum displayed value.
+        maxValue?: number, // An optional argument specifying the maximum displayed value.
+        count?: number // An optional argument specifying the number of displayed values.
+    ) => string; // Returns a human-readable string representation of the provided value.
+
+    parse: (
+        value: string | any // A string representation of a telemetry value or an already-parsed value.
+    ) => any; // Returns the value in its native type. This function should be idempotent.
+
+    validate: (value: string) => boolean; // Takes a string representation of a telemetry value and returns a boolean indicating whether the provided string can be parsed.
+}
+```
+
+##### Built-in Formats
+
+Open MCT on its own defines a handful of built-in formats:
+
+###### **Number Format (default):** 
+
+Applied to data with `format: 'number'`
+```js
+valueMetadata = {
+    format: 'number'
+    // ...
+};
+```
+
+```ts
+interface NumberFormatter extends Formatter {
+    parse: (x: any) => number;
+    format: (x: number) => string;
+    validate: (value: any) => boolean;
+}
+```
+###### **String Format**:
+
+Applied to data with `format: 'string'`
+```js
+valueMetadata = {
+    format: 'string'
+    // ...
+};
+```
+```ts
+interface StringFormatter extends Formatter {
+    parse: (value: any) => string;
+    format: (value: string) => string;
+    validate: (value: any) => boolean;
+}
+```
+
+###### **Enum Format**:
+Applied to data with `format: 'enum'`
+```js
+valueMetadata = {
+    format: 'enum',
+    enumerations: [
+    {
+        value: 1,
+        string: 'APPLE'
+    }, 
+    {
+        value: 2,
+        string: 'PEAR',
+    },
+    {
+        value: 3,
+        string: 'ORANGE'
+    }]
+    // ...
+};
+```
+
+Creates a two-way mapping between enum string and value to be used in the `parse` and `format` methods.
+Ex:
+- `formatter.parse('APPLE') === 1;`
+- `formatter.format(1) === 'APPLE';`
+
+```ts
+interface EnumFormatter extends Formatter {
+    parse: (value: string) => string;
+    format: (value: number) => string;
+    validate: (value: any) => boolean;
+}
+```
 
 ##### Registering Formats
 
+Formats implement the following interface (provided here as TypeScript for simplicity):
+
+
 Formats are registered with the Telemetry API using the `addFormat` function. eg.
 
-``` javascript
+```javascript
 openmct.telemetry.addFormat({
     key: 'number-to-string',
     format: function (number) {

e2e/README.md

@@ -193,7 +193,7 @@ Current list of test tags:
 |`@ipad` | Test case or test suite is compatible with Playwright's iPad support and Open MCT's read-only mobile view (i.e. no create button).|
 |`@gds` | Denotes a GDS Test Case used in the VIPER Mission.|
 |`@addInit` | Initializes the browser with an injected and artificial state. Useful for loading non-default plugins. Likely will not work outside of `npm start`.|
-|`@localStorage` | Captures or generates session storage to manipulate browser state. Useful for excluding in tests which require a persistent backend (i.e. CouchDB).|
+|`@localStorage` | Captures or generates session storage to manipulate browser state. Useful for excluding in tests which require a persistent backend (i.e. CouchDB). See [note](#utilizing-localstorage)|
 |`@snapshot` | Uses Playwright's snapshot functionality to record a copy of the DOM for direct comparison. Must be run inside of the playwright container.|
 |`@unstable` | A new test or test which is known to be flaky.|
 |`@2p` | Indicates that multiple users are involved, or multiple tabs/pages are used. Useful for testing multi-user interactivity.|
@@ -352,6 +352,28 @@ By adhering to this principle, we can create tests that are both robust and refl
   1.  Avoid repeated setup to test a single assertion. Write longer tests with multiple soft assertions.
   This ensures that your changes will be picked up with large refactors.
 
+##### Utilizing LocalStorage
+  1. In order to save test runtime in the case of tests that require a decent amount of initial setup (such as in the case of testing complex displays), you may use [Playwright's `storageState` feature](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state) to generate and load localStorage states.
+  1. To generate a localStorage state to be used in a test:
+    - Add an e2e test to our generateLocalStorageData suite which sets the initial state (creating/configuring objects, etc.), saving it in the `test-data` folder:
+    ```js
+    // Save localStorage for future test execution
+    await context.storageState({
+      path: path.join(__dirname, '../../../e2e/test-data/display_layout_with_child_layouts.json')
+    });
+    ```
+    - Load the state from file at the beginning of the desired test suite (within the `test.describe()`). (NOTE: the storage state will be used for each test in the suite, so you may need to create a new suite):
+    ```js
+      const LOCALSTORAGE_PATH = path.resolve(
+        __dirname,
+        '../../../../test-data/display_layout_with_child_layouts.json'
+      );
+      test.use({
+        storageState: path.resolve(__dirname, LOCALSTORAGE_PATH)
+      }); 
+    ```
+
+
 ### How to write a great test
 
 - Avoid using css locators to find elements to the page. Use modern web accessible locators like `getByRole`

e2e/test-data/display_layout_with_child_layouts.json

@@ -0,0 +1,22 @@
+{
+  "cookies": [],
+  "origins": [
+    {
+      "origin": "http://localhost:8080",
+      "localStorage": [
+        {
+          "name": "mct",
+          "value": "{\"mine\":{\"identifier\":{\"key\":\"mine\",\"namespace\":\"\"},\"name\":\"My Items\",\"type\":\"folder\",\"composition\":[{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"}],\"location\":\"ROOT\",\"modified\":1732413602020,\"created\":1732413601160,\"persisted\":1732413602020},\"764a490f-4a83-4874-a062-e38c112f69c7\":{\"identifier\":{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"},\"name\":\"Parent Display Layout\",\"type\":\"layout\",\"composition\":[{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},{\"key\":\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"namespace\":\"\"}],\"configuration\":{\"items\":[{\"width\":32,\"height\":18,\"x\":1,\"y\":30,\"identifier\":{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},\"hasFrame\":true,\"fontSize\":\"default\",\"font\":\"default\",\"type\":\"subobject-view\",\"id\":\"9acce141-5291-427d-8785-847faa2707e6\"},{\"width\":32,\"height\":18,\"x\":30,\"y\":1,\"identifier\":{\"key\":\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"namespace\":\"\"},\"hasFrame\":true,\"fontSize\":\"default\",\"font\":\"default\",\"type\":\"subobject-view\",\"id\":\"9f89d6f6-fb7f-4af3-9cc3-4c5d0864e908\"}],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413605120,\"location\":\"mine\",\"created\":1732413602020,\"persisted\":1732413605120},\"801d3a35-91ac-43ae-b175-bc1be65f3587\":{\"name\":\"Child Layout 1\",\"type\":\"layout\",\"identifier\":{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},\"composition\":[],\"configuration\":{\"items\":[],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413603140,\"location\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"created\":1732413603140,\"persisted\":1732413603140},\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\":{\"name\":\"Child Layout 2\",\"type\":\"layout\",\"identifier\":{\"key\":\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"namespace\":\"\"},\"composition\":[],\"configuration\":{\"items\":[],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413604240,\"location\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"created\":1732413604240,\"persisted\":1732413604240}}"
+        },
+        {
+          "name": "mct-recent-objects",
+          "value": "[{\"objectPath\":[{\"identifier\":{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"},\"name\":\"Parent Display Layout\",\"type\":\"layout\",\"composition\":[{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},{\"key\":\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"namespace\":\"\"}],\"configuration\":{\"items\":[{\"width\":32,\"height\":18,\"x\":1,\"y\":1,\"identifier\":{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},\"hasFrame\":true,\"fontSize\":\"default\",\"font\":\"default\",\"type\":\"subobject-view\",\"id\":\"9acce141-5291-427d-8785-847faa2707e6\"}],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413604240,\"location\":\"mine\",\"created\":1732413602020,\"persisted\":1732413604240},{\"identifier\":{\"key\":\"mine\",\"namespace\":\"\"},\"name\":\"My Items\",\"type\":\"folder\",\"composition\":[{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"}],\"location\":\"ROOT\",\"modified\":1732413602020,\"created\":1732413601160,\"persisted\":1732413602020},{\"identifier\":{\"key\":\"ROOT\",\"namespace\":\"\"},\"name\":\"Open MCT\",\"type\":\"root\",\"composition\":[{\"key\":\"mine\",\"namespace\":\"\"}]}],\"navigationPath\":\"/browse/mine/764a490f-4a83-4874-a062-e38c112f69c7\",\"domainObject\":{\"identifier\":{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"},\"name\":\"Parent Display Layout\",\"type\":\"layout\",\"composition\":[{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},{\"key\":\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"namespace\":\"\"}],\"configuration\":{\"items\":[{\"width\":32,\"height\":18,\"x\":1,\"y\":1,\"identifier\":{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},\"hasFrame\":true,\"fontSize\":\"default\",\"font\":\"default\",\"type\":\"subobject-view\",\"id\":\"9acce141-5291-427d-8785-847faa2707e6\"}],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413604240,\"location\":\"mine\",\"created\":1732413602020,\"persisted\":1732413604240}},{\"objectPath\":[{\"identifier\":{\"key\":\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"namespace\":\"\"},\"name\":\"Child Layout 2\",\"type\":\"layout\",\"composition\":[],\"configuration\":{\"items\":[],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413604240,\"location\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"created\":1732413604240,\"persisted\":1732413604240},{\"identifier\":{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"},\"name\":\"Parent Display Layout\",\"type\":\"layout\",\"composition\":[{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},{\"key\":\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"namespace\":\"\"}],\"configuration\":{\"items\":[{\"width\":32,\"height\":18,\"x\":1,\"y\":1,\"identifier\":{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},\"hasFrame\":true,\"fontSize\":\"default\",\"font\":\"default\",\"type\":\"subobject-view\",\"id\":\"9acce141-5291-427d-8785-847faa2707e6\"}],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413604240,\"location\":\"mine\",\"created\":1732413602020,\"persisted\":1732413604240},{\"identifier\":{\"key\":\"mine\",\"namespace\":\"\"},\"name\":\"My Items\",\"type\":\"folder\",\"composition\":[{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"}],\"location\":\"ROOT\",\"modified\":1732413602020,\"created\":1732413601160,\"persisted\":1732413602020},{\"identifier\":{\"key\":\"ROOT\",\"namespace\":\"\"},\"name\":\"Open MCT\",\"type\":\"root\",\"composition\":[{\"key\":\"mine\",\"namespace\":\"\"}]}],\"navigationPath\":\"/browse/mine/764a490f-4a83-4874-a062-e38c112f69c7/d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"domainObject\":{\"identifier\":{\"key\":\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"namespace\":\"\"},\"name\":\"Child Layout 2\",\"type\":\"layout\",\"composition\":[],\"configuration\":{\"items\":[],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413604240,\"location\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"created\":1732413604240,\"persisted\":1732413604240}},{\"objectPath\":[{\"identifier\":{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},\"name\":\"Child Layout 1\",\"type\":\"layout\",\"composition\":[],\"configuration\":{\"items\":[],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413603140,\"location\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"created\":1732413603140,\"persisted\":1732413603140},{\"identifier\":{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"},\"name\":\"Parent Display Layout\",\"type\":\"layout\",\"composition\":[{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},{\"key\":\"d70f3dfc-99c6-47f6-87c7-db8faed8598b\",\"namespace\":\"\"}],\"configuration\":{\"items\":[{\"width\":32,\"height\":18,\"x\":1,\"y\":1,\"identifier\":{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},\"hasFrame\":true,\"fontSize\":\"default\",\"font\":\"default\",\"type\":\"subobject-view\",\"id\":\"9acce141-5291-427d-8785-847faa2707e6\"}],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413604240,\"location\":\"mine\",\"created\":1732413602020,\"persisted\":1732413604240},{\"identifier\":{\"key\":\"mine\",\"namespace\":\"\"},\"name\":\"My Items\",\"type\":\"folder\",\"composition\":[{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"}],\"location\":\"ROOT\",\"modified\":1732413602020,\"created\":1732413601160,\"persisted\":1732413602020},{\"identifier\":{\"key\":\"ROOT\",\"namespace\":\"\"},\"name\":\"Open MCT\",\"type\":\"root\",\"composition\":[{\"key\":\"mine\",\"namespace\":\"\"}]}],\"navigationPath\":\"/browse/mine/764a490f-4a83-4874-a062-e38c112f69c7/801d3a35-91ac-43ae-b175-bc1be65f3587\",\"domainObject\":{\"identifier\":{\"key\":\"801d3a35-91ac-43ae-b175-bc1be65f3587\",\"namespace\":\"\"},\"name\":\"Child Layout 1\",\"type\":\"layout\",\"composition\":[],\"configuration\":{\"items\":[],\"layoutGrid\":[10,10]},\"notes\":\"framework/generateLocalStorageData.e2e.spec.js\\nGenerate Visual Test Data @localStorage @generatedata\\nGenerate display layout with 2 child display layouts\\nchrome\",\"modified\":1732413603140,\"location\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"created\":1732413603140,\"persisted\":1732413603140}},{\"objectPath\":[{\"identifier\":{\"key\":\"mine\",\"namespace\":\"\"},\"name\":\"My Items\",\"type\":\"folder\",\"composition\":[{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"}],\"location\":\"ROOT\",\"modified\":1732413602020,\"created\":1732413601160,\"persisted\":1732413602020},{\"identifier\":{\"key\":\"ROOT\",\"namespace\":\"\"},\"name\":\"Open MCT\",\"type\":\"root\",\"composition\":[{\"key\":\"mine\",\"namespace\":\"\"}]}],\"navigationPath\":\"/browse/mine\",\"domainObject\":{\"identifier\":{\"key\":\"mine\",\"namespace\":\"\"},\"name\":\"My Items\",\"type\":\"folder\",\"composition\":[{\"key\":\"764a490f-4a83-4874-a062-e38c112f69c7\",\"namespace\":\"\"}],\"location\":\"ROOT\",\"modified\":1732413602020,\"created\":1732413601160,\"persisted\":1732413602020}}]"
+        },
+        {
+          "name": "mct-tree-expanded",
+          "value": "[]"
+        }
+      ]
+    }
+  ]
+}

e2e/tests/framework/generateLocalStorageData.e2e.spec.js

@@ -55,6 +55,42 @@ test.describe('Generate Visual Test Data @localStorage @generatedata', () => {
     await page.goto('./', { waitUntil: 'domcontentloaded' });
   });
 
+  test('Generate display layout with 2 child display layouts', async ({ page, context }) => {
+    // Create Display Layout
+    const parent = await createDomainObjectWithDefaults(page, {
+      type: 'Display Layout',
+      name: 'Parent Display Layout'
+    });
+    const child1 = await createDomainObjectWithDefaults(page, {
+      type: 'Display Layout',
+      name: 'Child Layout 1',
+      parent: parent.uuid
+    });
+    const child2 = await createDomainObjectWithDefaults(page, {
+      type: 'Display Layout',
+      name: 'Child Layout 2',
+      parent: parent.uuid
+    });
+
+    await page.goto(parent.url);
+    await page.getByLabel('Edit').click();
+    await page.getByLabel(`${child2.name} Layout Grid`).hover();
+    await page.getByLabel('Move Sub-object Frame').nth(1).click();
+    await page.getByLabel('X:').fill('30');
+
+    await page.getByLabel(`${child1.name} Layout Grid`).hover();
+    await page.getByLabel('Move Sub-object Frame').first().click();
+    await page.getByLabel('Y:').fill('30');
+
+    await page.getByLabel('Save').click();
+    await page.getByRole('listitem', { name: 'Save and Finish Editing' }).click();
+
+    //Save localStorage for future test execution
+    await context.storageState({
+      path: path.join(__dirname, '../../../e2e/test-data/display_layout_with_child_layouts.json')
+    });
+  });
+
   // TODO: Visual test for the generated object here
   // - Move to using appActions to create the overlay plot
   //   and embedded standard telemetry object