`const testChannel = await fdc3.getOrCreateChannel("test-channel")` | +| B | 2.Broadcast | Broadcast an `fdc3.instrument` to the channel using:
`testChannel.broadcast(
Ensure that the instrument received by A is identical to that sent by B | + +- `ACBasicUsage2` Perform above test + +## Filtered Context + +| App | Step | Details | +|-----|--------------------|-----------------------------------------------------------------| +| A | 1.Retrieve `Channel` |Retrieve a `Channel` object representing an 'App' channel called `test-channel` using:
`const testChannel = await fdc3.getOrCreateChannel("test-channel")` | +| A | 2.Add Context Listener |Add an _typed_ context listener for `fdc3.instrument`, using:
`await testChannel.addContextListener("fdc3.instrument", handler)`| +| B | 3.Retrieve `Channel` |Retrieve a `Channel` object representing the same 'App' channel A did (`test-channel`)| +| B | 4.Broadcast | B broadcasts both an `fdc3.instrument` context and an `fdc3.contact` context, using:
`testChannel.broadcast(
`testChannel.broadcast(
Ensure that the fdc3.instrument received by A is identical to that sent by B
Ensure that the fdc3.contact context is NOT received. | + +- `ACFilteredContext1`: Perform above test. +- `ACFilteredContext2`: Perform above test, but add listeners for both `fdc3.instrument` and `fdc3.contact` in step2. Ensure that both context objects are received. +- `ACFilteredContext3`: Perform above test, except creating a _different_ channel in app B. Check that you _don't_ receive anything (as the channels don't match). +- `ACFilteredContext4`: Perform above test, except that after creating the channel **A** creates another channel with a further _different_ channel id and adds a further context listener to it. Ensure that **A** is still able to receive context on the first channel (i.e. it is unaffected by the additional channel) and does NOT receive anything on the second channel. +- `ACUnsubscribe`: Perform above test, except that after creating the channel **A** then `unsubscribe()`s the listener it added to the channel. Check that **A** does NOT receive anything. + +### App Channel History + +| App | Step | Details | +|-----|--------------------|---------------------------------------------------------| +| A | 1.Retrieve `Channel` |Retrieve a `Channel` object representing an 'App' channel called `test-channel` using:
`const testChannel = await fdc3.getOrCreateChannel("test-channel")` | +| B | 2.Retrieve `Channel` |Retrieve a `Channel` object representing the same 'App' channel A did (`test-channel`)| +| B | 3.Broadcast |B broadcasts both the instrument context and a contact context, using:
`testChannel.broadcast(
`testChannel.broadcast(
`await testChannel.addContextListener("fdc3.instrument", handler)`
Ensure that A does NOT receive any context via these listeners (past context is only retrieved via a `getCurrentContext()` call on App channels). | +| A | 5.Retrieve Current Context | A is able to retrieve the most recent context of each context type from the `Channel` via:
`const instrument = await testChannel.getCurrentContext('fdc3.instrument')`
`const instrument = await testChannel.getCurrentContext('fdc3.contact')`
Ensure that both contexts retrieved by A are identical to those sent by B| + +- `ACContextHistoryTyped`: Perform above test. +- `ACContextHistoryMultiple`: **B** Broadcasts multiple history items of both types. Ensure that only the last version of each type is received by **A**. +- `ACContextHistoryLast`: In step 5. **A** retrieves the _untyped_ current context of the channel via `const currentContext = await testChannel.getCurrentContext()`. Ensure that A receives only the very last broadcast context item _of any type_. diff --git a/docs/api/conformance/Basic-Tests.md b/docs/api/conformance/Basic-Tests.md new file mode 100644 index 000000000..d58c8b3e2 --- /dev/null +++ b/docs/api/conformance/Basic-Tests.md @@ -0,0 +1,33 @@ +--- +id: Basic-Tests +sidebar_label: Basic Tests +title: Basic Tests +hide_title: true +--- + +# Basic Tests + + +_These are some basic sanity tests implemented in the FDC3 Conformance Framework. It is expected that Desktop Agent testers will run these first before commencing the much more thorough tests in section 2 onwards._ + +- `BasicCL1`: You can create a context listener by calling `fdc3.addContextListener('fdc3.contact',
`sharedTestingIntent1(testContextX)` | addIntentListener() for given intents | +| B | Raise Intent tests with Context results | `bTestingIntent(testContextY)`
`sharedTestingIntent1(testContextX, testContextY) => testContextY` | addIntentListener() for given intents | +| C | Find Intent tests (never started) | `cTestingIntent(testContextX) => testContextZ` | addIntentListener() for given intents | +| D | Find Intent tests (never started) | `sharedTestingIntent2(testContextX) => testContextZ` | addIntentListener() for given intents | +| E | Find Intent & Raise Intent with Channel result | `sharedTestingIntent2(testContextY) => channel` | addIntentListener() for given intents | +| F | Find Intent & Raise Intent with PrivateChannel result | `sharedTestingIntent2(testContextY) => channel
starts app A. | +| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent1")` to register its listener.
It then receives `testContextX`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App A's `appId` and `instanceId` set.** | + +- `2.0-RaiseIntentSingleResolve`: Perform above test +- `2.0-RaiseIntentTargetedAppResolve`: Repeat the above test, but: + - In the first step use `fdc3.raiseIntent("sharedTestingIntent1", testContextX, {"appID": "
starts app A. | +| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent")` to register its listener.
It then receives `testContextX`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App A's `appId` and `instanceId` set. | +| Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | +| A | 5. return void | A should return `void` after a short delay (e.g. 5 seconds). | +| Test | 6. receive void result | The promise received by Test from `resolution.getResult()` should resolve to void. Confirm that the promise could be retrieved before the handler function returned and that the result was received _after_ the result was returned by A, NOT before. I.e. confirm that `resolution.getResult()` does NOT block until the result is returned, but rather returns a promise that can be awaited. | + +- `2.0-RaiseIntentVoidResult5secs`: Perform above test +- `2.0-RaiseIntentVoidResult0secs`: Perform above test, but A should return its result immediately (no delay). Ignore test step 6 (as there is too little time between the IntentResolution and IntentHandler completing). +- `2.0-RaiseIntentVoidResult61secs`: Perform above test, but A should return its result **after 61 seconds** (arbitrary delay to test timeout does NOT occur) + +## Raise Intent Result (Context result) + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1. Raise | `fdc3.raiseIntent("sharedTestingIntent1", testContextY)`
starts app **B**. | +| B | 2. Receive Intent & Context | After starting up, B runs `fdc3.addIntentListener("sharedTestingIntent1")` to register its listener.
It then receives `testContextY`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App B's `appId` and `instanceId` set. | +| Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | +| B | 5. return `testContextY` | B should return a `testContextY` instance after a short delay (e.g. 5 seconds). | +| Test | 6. receive context result | The promise received by Test from `resolution.getResult()` should resolve to the `testContextY` instance. Confirm that the promise could be retrieved before the handler function returned and that the result was received _after_ the result was returned by B, NOT before. I.e. confirm that `resolution.getResult()` does NOT block until the result is returned, but rather returns a promise that can be awaited. | + +- `2.0-RaiseIntentContextResult5secs`: Perform the above test. +- `2.0-RaiseIntentContextResult0secs`: Perform the previous test but B should return its result immediately (no delay). +- `2.0-RaiseIntentContextResult61secs`: As above, but B should return its result **after 61 seconds** (arbitrary delay to test timeout does NOT occur) + +## Raise Intent Result (Channel results) + +| App | Step | Details | +|-------|-----------------------|---------------------------------------------------------------------------------------------------| +| Test | 1. Raise Intent | Test raises an intent with `fdc3.raiseIntent("sharedTestingIntent2", testContextY, {appId: "
starts app E. | +| E | 2. Receive Intent & Context | After starting up, E runs `fdc3.addIntentListener("sharedTestingIntent2")` to register its listener.
It them receives `testContextY`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App E's `appId` and `instanceId` set. | +| Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | +| E | 5. return Channel | E should retrieve a Channel object via `fdc3.getOrCreateChannel("someChannelName")` and return it immediately. | +| Test | 6. receive Channel result | The promise received by Test from `resolution.getResult()` should resolve to a `Channel` object with the expected id. Confirm that the `type` of the Channel object is "app". | +| Test | 7. addContextListener | Add a context listener to the Channel object via `channelObj.addContextListener("testContextZ", handler)` | +| E | 8. broadcast context | After a short delay (of a few seconds) E should broadcast a `testContextZ` context object over the channel, including an `id` field with a unique identifier set (e.g. a uuid). | +| Test | 9. receive context | Test should receive the context broadcast by E and confirm that it contains the expected `id` value. | + +- `2.0-RaiseIntentChannelResult`: Perform the above test +- `2.0-RaiseIntentPrivateChannelResult`: Perform the above test, but: + - Substitute app F throughout - which returns a PrivateChannel result instead of channel. + - At step 5, the PrivateChannel should be created via`fdc3.createPrivateChannel()`. + - At step 6 confirm that the type of the channel is "private". + +## PrivateChannels cannot be accessed as app channels + +| App | Step | Details | +|-------|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1. Create a private channel | Test creates a PrivateChannel with `const privChan = await fdc3.createPrivateChannel()`. Confirm that the Channel has an `id`. | +| Test | 2. Confirm private channel `id` is unique | Test creates a second PrivateChannel with `const privChan = await fdc3.createPrivateChannel();`. Confirm that the Channel has an `id` and that it is distinct from the first channel created. | +| Test | 3. Retrieve as app channel | Attempt to retrieve the channels as App Channels with `const appChan = await fdc3.getOrCreateChannel(privChan.id)` this should fail with `ChannelError.AccessDenied` | +| Test | 4. Raise Intent & await result | Start app J and pass it the id of the second PrivateChannel with `fdc3.raiseIntent("privateChannelIsPrivate", privateChannelDetails)`, where the context object contains the id of the channel to attempt to retrieve. An IntentResolution should be returned and App J should start. Wait for a result to be returned via `await resolution.getResult()`. | +| J | 5. Receive Intent & Context | J should add an Intent Listener and receive the context with `fdc3.addIntentListener("privateChannelIsPrivate", handler)` | +| J | 6. Retrieve as app channel | J should attempt to retrieve the channel as an App Channel by `id` with `const appChan = await fdc3.getOrCreateChannel("
starts app K. | +| K | 2. Receive Intent & Context | After starting up, K runs `fdc3.addIntentListener("kTestingIntent")` to register its listener.
It them receives `testContextX`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App K's `appId` and `instanceId` set. | +| Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | +| K | 5. Create PrivateChannel and setup event listeners | K should create a `PrivateChannel` object via `const privChan = await fdc3.createPrivateChannel()`,
it should then add listeners for the 3 events offered + a context listener via:
- `const listener1 = await privChan.onAddContextListener(handler1);`
- `const listener2 = await privChan.onUnsubscribe(handler2);`
- `const listener3 = await privChan.onDisconnect(handler3);`
- `const listener4 = await privChan.addContextListener("testContextX", handler4)`
it should then return the `PrivateChannel`. | +| Test | 6. receive PrivateChannel | The promise received by Test from `resolution.getResult()` should resolve to a `PrivateChannel` object. Confirm that the `type` of the Channel object is "private". | +| Test | 7. addContextListener | Test should add a context listener to the PrivateChannel object via `const listener1 = privChan.addContextListener("testContextZ", handler)` | +| K | 8. Receive event & broadcast context | The `onAddContextListener` handler (`listener1`) added in step 5 should fire after Test adds its listener. Once it has, K should broadcast a short stream of `testContextZ` objects, with consecutive integer values in them (e.g. 1-5). | +| Test | 9. Unsubscribe listener | Test should confirm receipt of the expected context objects, in the expected order, broadcast by K. It should then remove its context listener with `listener1.unsubscribe().` | +| K | 10. Receive unsubscribe event | The event handler registered by K via `onUnsubscribe` should fire. If it does not and the test moves to a subsequent step, K should indicate this to the test runner (failing the test).| +| Test | 11. Broadcast context | Test should broadcast at least one `testContextX` object via the PrivateChannel (back to K). | +| K | 12. Receive context | K should confirm receipt of the expected context. If it does not and the test moves to a subsequent step K should indicate this to the test runner (failing the test).| +| Test | 13. re-run addContextListener | Test should (again) add a context listener to the PrivateChannel object via `const listener2 = privChan.addContextListener("testContextZ", handler)` | +| K | 14. Receive event & broadcast context | The `onAddContextListener` handler added in step 5 should (again) fire after Test adds its listener. Once it has, K should again broadcast a short stream of `testContextZ` objects, with consecutive integer values in them (e.g. 6-10). | +| Test | 15. Disconnect | Test should (again) confirm receipt of the expected context objects, in the expected order, broadcast by K. It should then disconnect from the channel with [`privChan.disconnect().`](https://fdc3.finos.org/docs/api/ref/PrivateChannel#disconnect) | +| K | 16. Receive events & cleanup | The `onUnsubscribe` handler added in step 5 should (again) fire after Test calls `privChan.disconnect()`. Subsequently, the `onDisconnect` handler also added in step 5 should fire. Once it has, K can unsubscribe its listeners, indicate to the test runner that all steps were completed and close. | + +- `2.0-PrivateChannelsLifecycleEvents`: Perform the above test. + +## Resolving Ambiguous Intents + +FDC3 Desktop Agent MUST provide a method of resolving ambiguous intents (i.e. those that might be resolved by multiple applications) or unspecified intents (calls to raiseIntentForContext that return multiple options). This is often accomplished by providing a user interface allowing the user to select the desired target application or intent and application. + +As the methods of resolving ambiguous intents are often user interactive, it is either difficult or impossible to implement an automated test for this. Hence, manual tests should be performed as a final step in a conformance test. These tests are based on the same applications defined for and used in other intent tests - however a separate manual test app should be provided to enable the test. + +| App | Step | Details | +|---|---|---| +| Test | 1. Raise Ambiguous Intent | `fdc3.raiseIntent("sharedTestingIntent2", testContextY)` | +| User | 2. Chooser Interaction | A method of resolving the ambiguous request is provided (such as a User Interface allowing the user to choose an application or instance) for choosing one of `E`,`F`,`G`,`H` and `I`. | + +- `2.0-ResolveAmbiguousIntentTarget`: Perform above steps to invoke intent resolution for an unspecified target with multiple options. Confirm that test is able to complete successfully. + +| App | Step | Details | +|---|---|---| +| Test | 1. Raise Ambiguous Intent | `fdc3.raiseIntentForContext(testContextY)` | +| User | 2. Chooser Interaction | A method of resolving the ambiguous request is provided (such as a User Interface allowing the user to choose an application or instance) for choosing one of `E`,`F`,`G`,`H` and `I`. | + +- `2.0-ResolveAmbiguousContextTarget`: Perform above steps to invoke intent resolution for an unspecified target with multiple options. Confirm that test is able to complete successfully. + +| App | Step | Details | +|---|---|---| +| Test | 1. Open 4 Apps | Use `fdc3.open()` to open 2 instances of App `E` and 2 instances of `F`. | +| Test | 2. Raise Ambiguous Intent | `fdc3.raiseIntent("sharedTestingIntent2", testContextY)` | +| User | 3. Chooser Interaction | A method of resolving the ambiguous request is provided (such as a User Interface allowing the user to choose an application or instance) for choosing one of `E (1)`,`F (1)`,`E (2)`,`F (2)` and options to open `G`, `H` and `I` | + +- `2.0-ResolveAmbiguousIntentTargetMultiInstance`: Perform above steps to invoke intent resolution for an unspecified target with multiple options. Confirm that test is able to complete successfully. + +| App | Step | Details | +|---|---|---| +| Test | 1. Open 4 Apps | Use `fdc3.open()` to open 2 instances of App `E` and 2 instances of `F`. | +| Test | 2. Raise Ambiguous Intent | `fdc3.raiseIntentForContext(testContextY)` | +| User | 3. Chooser Interaction | A method of resolving the ambiguous request is provided (such as a User Interface allowing the user to choose an application or instance) for choosing one of `E (1)`,`F (1)`,`E (2)`,`F (2)` and options to open `G`, `H` and `I` | + +- `2.0-ResolveAmbiguousContextTargetMultiInstance`: Perform above steps to invoke intent resolution for an unspecified target with multiple options. Confirm that test is able to complete successfully. diff --git a/docs/api/conformance/Metadata-Tests.md b/docs/api/conformance/Metadata-Tests.md new file mode 100644 index 000000000..29ebac028 --- /dev/null +++ b/docs/api/conformance/Metadata-Tests.md @@ -0,0 +1,69 @@ +--- +id: Metadata-Tests +sidebar_label: Metadata Tests +title: Metadata Tests +hide_title: true +--- + +# Metadata & Instance Test Cases + + +You will need to pre-populate the AppDirectory with the following items: + +| App | Required Metadata | +|-----|------------------------------------------| +| A | Generic AppD Record which contains at least the following fields:
- `name`
- `version`
- `title`
- `tooltip`
- `description`
- `icons` (`Array
- `screenshots` (`Array
- `interop.intents.listensFor` (`aTestingIntent` with at least context type `testContextX`) | + +## Retrieve `AppMetadata` + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1.getAppMetadata | Retrieve metadata for the configured app A with
`const metadata1 = await fdc3.getAppMetadata({appId: "
`const appIdentifier1 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId`. | +| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | +| Test | 3.getAppMetadata1 | Retrieve metadata for the first instance of the app with
`const metadata1 = fdc3.getAppMetadata(appIdentifier1)` | +| Test | 4.Confirm1 | Compare the `AppMetadata` object to the expected definition for the fields provided above during setup and ensure that the metadata matches. | +| Test | 5.getAppMetadata2 | Retrieve metadata for the second instance of the app with
`const metadata2 = fdc3.getAppMetadata(appIdentifier2)` | +| Test | 6.Confirm2 | An `instanceId` should be provided, confirm that it matches the one in `appIdentifier2` | + +- `AppInstanceMetadata`: Perform the above steps. + +## Finding Instances + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1.Open1 | Open the first instance of App A using
`const appIdentifier1 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId`. | +| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | +| Test | 3.FindInstances | Retrieve details of open instances of app A with
`let instances = await fdc3.findInstances({appId: "
confirm that both `appIdentifier1` and `appIdentifier2` are both present in the array. | +| Test | 4.RaiseIntent | Use `appIdentifier1` to raise an intent and target that instance, with
`const resolution = fdc3.raiseIntent("aTestingIntent", {"type": "testContextX"}, appIdentifier1)` | +| Test | 5.Confirm1 | Check that `resolution.source` matches `appIdentifier1` | +| A | 6.ConfirmReceipt | Ensure that the instance of app A represented by `appIdentifier1` received the raised intent | + +- `FindInstances`: Perform the above steps. + +## Getting Info For The Agent + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1.getInfo |Retrieve the `ImplementationMetadata` for the DesktopAgent with
- `fdc3.getInfo().then((implMetadata) => { subsequent steps }`
**Note that the use of `then` is deliberate and intended to confirm that a promise returned (as this function switched from synchronous to asynchronous in 2.0)**| +| Test | 2.CheckVersion | Check that the `fdc3Version` variable is present and at or greater than:
- 2.0
(which you can do with the [`versionIsAtLeast` function from FDC3's Methods.ts](https://github.com/finos/FDC3/blob/add64f8302c6dcdc8437cf0e245101e927b69ec2/src/api/Methods.ts#L207):
`const isFDC3v2 = versionIsAtLeast(implMetadata, "2.0")` | +| Test | 3.CheckProvider | Check that the `provider` variable is present and not an empty string | +| Test | 4.CheckFeatures | Check that the `optionalFeatures`, `optionalFeatures.OriginatingAppMetadata` and `optionalFeatures.UserChannelMembershipAPIs` variables are all present and that the latter two provide boolean values | + +- `GetInfo1`: Perform the above steps. + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1.Open1 | Start an instance of App A with
`const appIdentifier1 = await fdc3.open({appId: "
retrieve its `AppIdentifier` with instance details. Confirm that the `AppIdentifier` contains both an `appId` and `instanceId` | +| A | 2.getInfo | Retrieve the `ImplementationMetadata` for the DesktopAgent with:
`fdc3.getInfo().then((implMetadata) => { ... subsequent steps ...}`
This should include `AppMetadata` for the retrieving app. | +| A + Test | 3.Confirm | Check that `implMetadata.appMetadata` contains an `appId` and `instanceId` matching that retrieved in the first step (will require transmission of the details from A to Test or vice-versa). Also compare the `AppMetadata` object to the expected definition for the fields provided above during setup and ensure that the metadata matches. | + +- `GetInfo2`: Perform the above steps. diff --git a/docs/api/conformance/Open-Tests.md b/docs/api/conformance/Open-Tests.md new file mode 100644 index 000000000..08cb9eb62 --- /dev/null +++ b/docs/api/conformance/Open-Tests.md @@ -0,0 +1,45 @@ +--- +id: Open-Tests +sidebar_label: Open Tests +title: Open Tests +hide_title: true +--- + +# Open Tests + + +## A Opens B + +| App | Step | Description | +|-----|-----------------|----------------------------------------------------------| +| A | 1. Opening App | App A calls a function (see below) to open a second app, B | +| A | 2. Check Metadata | Ensure that the correct app was opened | + +- `AOpensB3`: **A** uses an `AppMetadata` or `AppIdentifier` to open B, via: + - `fdc3.open({appId: “
`fdc3.addContextListener(null, handler)`
B receives an `fdc3.instrument` Context Object matching that passed to the `fdc3.open() call made by A | + +- `AOpensBWithContext3`: **A** uses an `AppMetadata` or `AppIdentifier` to open B, via: + - `fdc3.open({appId: “
A promise resolving to a `Listener` object is returned
Check that this has an `unsubscribe` method. | +| A | 2.joinUserChannel |A joins the first available (non-global) user channel. The available Channels are retrieved with:
`fdc3.getUserChannels()`
The first channel (that does not have the id 'global') is joined with:
`fdc3.joinUserChannel(
Check a `void` promise is returned. | +| A | 5.Receive Context | A receives the instrument object, matching the one broadcast by B. | + +- `UCBasicUsage1` Perform above test. +- `UCBasicUsage2` Perform steps in order: 2,1,3,4,5 to confirm that the order of `joinUserChannel` and `addContextListener` calls doesn't matter. +- `UCBasicUsage3` Perform steps in order: 3,4,1,2,5 to confirm that the current context is automatically received on joining a channel. +- `UCBasicUsage4` Perform steps in order: 3,4,2,1,5 to confirm that the current context is automatically received on adding a context listener to an already joined a channel. + +## Filtered Broadcast + +| App | Step |Details | +|-----|--------------------|----------------------------------------------------------------------------------| +| A | 1.addContextListener |A adds a `fdc3.instrument` _typed_ Context Listener using `addContextListener("fdc3.instrument", handler)`.
A promise resolving a `Listener` object is returned
Check that this has an `unsubscribe` function.| +| A | 2.joinUserChannel |A joins the first available user channel using:
`getUserChannels()` Check **user** channels are returned.
Call `fdc3.joinChannel()` on the first non-global channel.| +| B | 3.joinUserChannel |B joins the same channel as A, via the same process in 2. | +| B | 4.Broadcast | B broadcasts:
1.`fdc3.broadcast(
2. `fdc3.broadcast()`
Check a `void` promise is returned. | +| A | 5.Receive Context | A receives the `fdc3.instrument` object, matching the one broadcast by B.
Check that the `fdc3.contact` is NOT received. | + +- `UCFilteredUsage1` Perform above test. +- `UCFilteredUsage2` Perform steps in order: 2,1,3,4,5. +- `UCFilteredUsage3` Perform steps in order: 3,4,1,2,5. +- `UCFilteredUsage4` Perform steps in order: 3,4,2,1,5. + +## Broadcast With Multiple Listeners + +| App | Step | Details | +|-----|--------------------|-------------------------------------------------------------------------------------------------------------| +| A | 1.addContextListeners | A sets up two Context Listeners. One for `fdc3.instrument` and one for `fdc3.contact` by calling: `addContextListener ("fdc3.instrument", handler)`
`addContextListener ("fdc3.contact", handler)`
A promise resolving a `Listener` object is returned for each.
Check that this has an `unsubscribe` method for each. | +| A | 2.joinUserChannel |A joins the first available user channel using:
`getUserChannels()` Check **user** channels are returned.
Call `fdc3.joinChannel()` on the first non-global channel.| +| B | 3.joinUserChannel |B joins the same channel as A, via the same process in 2. | +| B | 4.Broadcast | `fdc3.broadcast(
`fdc3.broadcast(
A's `fdc3.contact` object matches the one broadcast by B, and arrives on the correct listener. | + +- `UCFilteredUsage5`: Perform above test. +- `UCFilteredUsage6`: Perform above test, except B will join a _different_ channel to A. Check that you _don't_ receive anything. +- `UCFilteredUsageChange`: Perform above test, except that after joining, **A** changes channel to a _different_ channel via a further call to `fdc3.joinUserChannel`. Check that **A** does NOT receive anything. +- `UCFilteredUsageUnsubscribe`: Perform above test, except that after joining, **A** then `unsubscribe()`s from the channel using the `listener.unsubscribe` function. Check that **A** does NOT receive anything. +- `UCFilteredUsageLeave`: Perform above test, except that immediately after joining, **A** _leaves the channel_, and so receives nothing. +- `UCFilteredUsageNoJoin`: Perform the above test, but skip step 2 so that **A** does NOT join a channel. Confirm that the _current channel_ for **A** is NOT set before continuing with the rest of the test. **A** should receive nothing. diff --git a/docs/context/ref/Action.md b/docs/context/ref/Action.md index 85800d3cf..8e26904aa 100644 --- a/docs/context/ref/Action.md +++ b/docs/context/ref/Action.md @@ -8,7 +8,10 @@ sidebar_label: Action A representation of an FDC3 Action (specified via a Context or Context & Intent) that can be inserted inside another object, for example a chat message. -The action may be completed by calling `fdc3.raiseIntent()` with the specified Intent and Context, or, if only a context is specified, by calling `fdc3.raiseIntentForContext()` (which the Desktop Agent will resolve by presenting the user with a list of available Intents for the Context). +The action may be completed by calling: +- `fdc3.raiseIntent()` with the specified Intent and Context +- `fdc3.raiseIntentForContext()` if only a context is specified, (which the Desktop Agent will resolve by presenting the user with a list of available Intents for the Context). +- `channel.broadcast()` with the specified Context, if the `broadcast` action has been defined. Accepts an optional `app` parameter in order to specify a specific app. @@ -22,6 +25,19 @@ Accepts an optional `app` parameter in order to specify a specific app. ## Properties +
+
+
+**type**: `string` with values:
+- `broadcast`,
+- `raiseIntent`
+
+The **action** field indicates the type of action:
+- **raiseIntent** : If no action or `raiseIntent` is specified, then `fdc3.raiseIntent` or `fdc3.raiseIntentForContext` will be called with the specified context (and intent if given).
+- **broadcast** : If `broadcast` and a `channelId` are specified then `fdc3.getOrCreateChannel(channelId)` is called to retrieve the channel and broadcast the context to it with `channel.broadcast(context)`. If no `channelId` has been specified, the context should be broadcast to the current channel (`fdc3.broadcast()`)
+
+
+
action
+
+**type**: `string` with values:
+- `broadcast`,
+- `raiseIntent`
+
+The **action** field indicates the type of action:
+- **raiseIntent** : If no action or `raiseIntent` is specified, then `fdc3.raiseIntent` or `fdc3.raiseIntentForContext` will be called with the specified context (and intent if given).
+- **broadcast** : If `broadcast` and a `channelId` are specified then `fdc3.getOrCreateChannel(channelId)` is called to retrieve the channel and broadcast the context to it with `channel.broadcast(context)`. If no `channelId` has been specified, the context should be broadcast to the current channel (`fdc3.broadcast()`)
+
+title (required)
@@ -50,20 +66,30 @@ A context object with which the action will be performed
+
+
+**type**: `string`
+
+Optional channel on which to broadcast the context. The `channelId` property is ignored unless the `action` is broadcast.
+
+
+
channelId
+
+**type**: `string`
+
+Optional channel on which to broadcast the context. The `channelId` property is ignored unless the `action` is broadcast.
+
+app
**type**: api/AppIdentifier
-An optional target application identifier that should perform the action
+An optional target application identifier that should perform the action. The `app` property is ignored unless the action is raiseIntent.
+
+
+**type**: `object`
+
+**Subproperties:**
+
+
+
+## Example
+
+```json
+{
+ "type": "fdc3.fileAttachment",
+ "data": {
+ "name": "myImage.png",
+ "dataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
+ }
+}
+```
+
diff --git a/docs/context/ref/Message.md b/docs/context/ref/Message.md
index 23c5c942c..41703b868 100644
--- a/docs/context/ref/Message.md
+++ b/docs/context/ref/Message.md
@@ -55,10 +55,10 @@ A map of string mime-type to string content
data (required)
+
+**type**: `object`
+
+**Subproperties:**
+
+
+
+
+**type**: `string`
+
+The name of the attached file
+
+
+
+name (required)
+
+**type**: `string`
+
+The name of the attached file
+
+
+
+
+**type**: `string`
+
+A data URI encoding the content of the file to be attached
+
+
+
+dataUri (required)
+
+**type**: `string`
+
+A data URI encoding the content of the file to be attached
+
+Additional Properties
-**Any of:**
+**One of:**
- **type**: [Action](Action)
-- **type**: `object`
+- **type**: [File Attachment](FileAttachment)
starts app B. | -| B | 2. Gather Context | `fdc.addIntentListener(‘sharedTestingIntent1’)`
Receives testContextY, matching that sent by D | +| D | 1. Raise | `fdc3.raiseIntent(‘sharedTestingIntent1’, {testContextY})`
starts app B. | +| B | 2. Gather Context | `fdc.addIntentListener(‘sharedTestingIntent1’)`
Receives testContextY, matching that sent by D | - `SingleResolve1`: Perform above test - `TargetedResolve1`: Use `fdc3.raiseIntent(‘aTestingIntent’, {testContextX},
starts app A. | -| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent1")` to register its listener.
It then receives `testContextX`, matching that sent by Test | +| Test | 1. Raise | `fdc3.raiseIntent("aTestingIntent", testContextX)`
starts app A. | +| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent1")` to register its listener.
It then receives `testContextX`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App A's `appId` and `instanceId` set.** | - `2.0-RaiseIntentSingleResolve`: Perform above test @@ -163,8 +170,8 @@ Finally, please note that this is a larger set of apps than were required for 1. | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| -| Test | 1. Raise | `fdc3.raiseIntent("aTestingIntent", testContextX)`
starts app A. | -| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent")` to register its listener.
It then receives `testContextX`, matching that sent by Test | +| Test | 1. Raise | `fdc3.raiseIntent("aTestingIntent", testContextX)`
starts app A. | +| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent")` to register its listener.
It then receives `testContextX`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App A's `appId` and `instanceId` set. | | Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | | A | 5. return void | A should return `void` after a short delay (e.g. 5 seconds). | @@ -178,8 +185,8 @@ Finally, please note that this is a larger set of apps than were required for 1. | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| -| Test | 1. Raise | `fdc3.raiseIntent("sharedTestingIntent1", testContextY)`
starts app **B**. | -| B | 2. Receive Intent & Context | After starting up, B runs `fdc3.addIntentListener("sharedTestingIntent1")` to register its listener.
It then receives `testContextY`, matching that sent by Test | +| Test | 1. Raise | `fdc3.raiseIntent("sharedTestingIntent1", testContextY)`
starts app **B**. | +| B | 2. Receive Intent & Context | After starting up, B runs `fdc3.addIntentListener("sharedTestingIntent1")` to register its listener.
It then receives `testContextY`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App B's `appId` and `instanceId` set. | | Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | | B | 5. return `testContextY` | B should return a `testContextY` instance after a short delay (e.g. 5 seconds). | @@ -193,8 +200,8 @@ Finally, please note that this is a larger set of apps than were required for 1. | App | Step | Details | |-------|-----------------------|---------------------------------------------------------------------------------------------------| -| Test | 1. Raise Intent | Test raises an intent with `fdc3.raiseIntent("sharedTestingIntent2", testContextY, {appId: "
starts app E. | -| E | 2. Receive Intent & Context | After starting up, E runs `fdc3.addIntentListener("sharedTestingIntent2")` to register its listener.
It them receives `testContextY`, matching that sent by Test | +| Test | 1. Raise Intent | Test raises an intent with `fdc3.raiseIntent("sharedTestingIntent2", testContextY, {appId: "
starts app E. | +| E | 2. Receive Intent & Context | After starting up, E runs `fdc3.addIntentListener("sharedTestingIntent2")` to register its listener.
It them receives `testContextY`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App E's `appId` and `instanceId` set. | | Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | | E | 5. return Channel | E should retrieve a Channel object via `fdc3.getOrCreateChannel("someChannelName")` and return it immediately. | @@ -227,11 +234,11 @@ Finally, please note that this is a larger set of apps than were required for 1. | App | Step | Details | |-------|-----------------|---------------------------------------------------------------------------------------------------| -| Test | 1. Raise intent | Test raises an intent with `fdc3.raiseIntent(‘"kTestingIntent", testContextX, {appId: "
starts app K. | -| K | 2. Receive Intent & Context | After starting up, K runs `fdc3.addIntentListener("kTestingIntent")` to register its listener.
It them receives `testContextX`, matching that sent by Test | +| Test | 1. Raise intent | Test raises an intent with `fdc3.raiseIntent(‘"kTestingIntent", testContextX, {appId: "
starts app K. | +| K | 2. Receive Intent & Context | After starting up, K runs `fdc3.addIntentListener("kTestingIntent")` to register its listener.
It them receives `testContextX`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App K's `appId` and `instanceId` set. | | Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | -| K | 5. Create PrivateChannel and setup event listeners | K should create a `PrivateChannel` object via `const privChan = await fdc3.createPrivateChannel()`,
it should then add listeners for the 3 events offered + a context listener via:
- `const listener1 = await privChan.onAddContextListener(handler1);`
- `const listener2 = await privChan.onUnsubscribe(handler2);`
- `const listener3 = await privChan.onDisconnect(handler3);`
- `const listener4 = await privChan.addContextListener("testContextX", handler4)`
it should then return the `PrivateChannel`. | +| K | 5. Create PrivateChannel and setup event listeners | K should create a `PrivateChannel` object via `const privChan = await fdc3.createPrivateChannel()`,
it should then add listeners for the 3 events offered + a context listener via:
- `const listener1 = await privChan.onAddContextListener(handler1);`
- `const listener2 = await privChan.onUnsubscribe(handler2);`
- `const listener3 = await privChan.onDisconnect(handler3);`
- `const listener4 = await privChan.addContextListener("testContextX", handler4)`
it should then return the `PrivateChannel`. | | Test | 6. receive PrivateChannel | The promise received by Test from `resolution.getResult()` should resolve to a `PrivateChannel` object. Confirm that the `type` of the Channel object is "private". | Test | 7. addContextListener | Test should add a context listener to the PrivateChannel object via `const listener1 = privChan.addContextListener("testContextZ", handler)` | | K | 8. Receive event & broadcast context | The `onAddContextListener` handler (`listener1`) added in step 5 should fire after Test adds its listener. Once it has, K should broadcast a short stream of `testContextZ` objects, with consecutive integer values in them (e.g. 1-5). | diff --git a/toolbox/fdc3-conformance/Metadata-Tests.md b/website/versioned_docs/version-2.0/api/conformance/Metadata-Tests.md similarity index 87% rename from toolbox/fdc3-conformance/Metadata-Tests.md rename to website/versioned_docs/version-2.0/api/conformance/Metadata-Tests.md index 8fdcaf2f7..456b4bff3 100644 --- a/toolbox/fdc3-conformance/Metadata-Tests.md +++ b/website/versioned_docs/version-2.0/api/conformance/Metadata-Tests.md @@ -1,11 +1,17 @@ +--- +id: Metadata-Tests +sidebar_label: Metadata Tests +title: Metadata Tests +hide_title: true +--- -# Metadata & Instance Test Cases +# Metadata & Instance Test Cases You will need to pre-populate the AppDirectory with the following items: | App | Required Metadata | |-----|------------------------------------------| -| A | Generic AppD Record which contains at least the following fields:
- `name`
- `version`
- `title`
- `tooltip`
- `description`
- `icons` (`Array
- `screenshots` (`Array
- `interop.intents.listensFor` (`aTestingIntent` with at least context type `testContextX`) | +| A | Generic AppD Record which contains at least the following fields:
- `name`
- `version`
- `title`
- `tooltip`
- `description`
- `icons` (`Array
- `screenshots` (`Array
- `interop.intents.listensFor` (`aTestingIntent` with at least context type `testContextX`) | ## Retrieve `AppMetadata`  @@ -21,7 +27,7 @@ You will need to pre-populate the AppDirectory with the following items: | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| | Test | 1.Open1 | Open a first instance of App A using
`const appIdentifier1 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId`. | -| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | +| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | | Test | 3.getAppMetadata1 | Retrieve metadata for the first instance of the app with
`const metadata1 = fdc3.getAppMetadata(appIdentifier1)` | | Test | 4.Confirm1 | Compare the `AppMetadata` object to the expected definition for the fields provided above during setup and ensure that the metadata matches. | | Test | 5.getAppMetadata2 | Retrieve metadata for the second instance of the app with
`const metadata2 = fdc3.getAppMetadata(appIdentifier2)` | @@ -34,7 +40,7 @@ You will need to pre-populate the AppDirectory with the following items: | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| | Test | 1.Open1 | Open the first instance of App A using
`const appIdentifier1 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId`. | -| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | +| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | | Test | 3.FindInstances | Retrieve details of open instances of app A with
`let instances = await fdc3.findInstances({appId: "
confirm that both `appIdentifier1` and `appIdentifier2` are both present in the array. | | Test | 4.RaiseIntent | Use `appIdentifier1` to raise an intent and target that instance, with
`const resolution = fdc3.raiseIntent("aTestingIntent", {"type": "testContextX"}, appIdentifier1)` | | Test | 5.Confirm1 | Check that `resolution.source` matches `appIdentifier1` | @@ -47,7 +53,7 @@ You will need to pre-populate the AppDirectory with the following items: | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| | Test | 1.getInfo |Retrieve the `ImplementationMetadata` for the DesktopAgent with
-  `let implMetadata = fdc3.getInfo()`
-  `fdc3.getInfo().then((implMetadata) => { subsequent steps }`
**Note that the use of `then` is deliberate and intended to confirm that a promise returned (as this function switched from synchronous to asynchronous in 2.0)**| -| Test | 2.CheckVersion | Check that the `fdc3Version` variable is present and at or greater than:
-  1.2
-  2.0
(which you can do with the [`versionIsAtLeast` function from FDC3's Methods.ts](https://github.com/finos/FDC3/blob/add64f8302c6dcdc8437cf0e245101e927b69ec2/src/api/Methods.ts#L207):
`const isFDC3v2 = versionIsAtLeast(implMetadata, "2.0")` | +| Test | 2.CheckVersion | Check that the `fdc3Version` variable is present and at or greater than:
-  1.2
-  2.0
(which you can do with the [`versionIsAtLeast` function from FDC3's Methods.ts](https://github.com/finos/FDC3/blob/add64f8302c6dcdc8437cf0e245101e927b69ec2/src/api/Methods.ts#L207):
`const isFDC3v2 = versionIsAtLeast(implMetadata, "2.0")` | | Test | 3.CheckProvider | Check that the `provider` variable is present and not an empty string | | Test | 4.CheckFeatures |  Check that the `optionalFeatures`, `optionalFeatures.OriginatingAppMetadata` and `optionalFeatures.UserChannelMembershipAPIs` variables are all present and that the latter two provide boolean values | diff --git a/toolbox/fdc3-conformance/Open-Tests.md b/website/versioned_docs/version-2.0/api/conformance/Open-Tests.md similarity index 98% rename from toolbox/fdc3-conformance/Open-Tests.md rename to website/versioned_docs/version-2.0/api/conformance/Open-Tests.md index 2e504d3e5..85e8f0aa6 100644 --- a/toolbox/fdc3-conformance/Open-Tests.md +++ b/website/versioned_docs/version-2.0/api/conformance/Open-Tests.md @@ -1,4 +1,11 @@ -# Open Tests +--- +id: Open-Tests +sidebar_label: Open Tests +title: Open Tests +hide_title: true +--- + +# Open Tests ## A Opens B diff --git a/website/versioned_docs/version-2.0/api/conformance/Overview.md b/website/versioned_docs/version-2.0/api/conformance/Overview.md new file mode 100644 index 000000000..1cd4d9df1 --- /dev/null +++ b/website/versioned_docs/version-2.0/api/conformance/Overview.md @@ -0,0 +1,21 @@ +--- +id: Conformance-Overview +sidebar_label: Overview +title: FDC3 Conformance Tests +hide_title: true +--- + +# FDC3 Conformance Tests + +This section contains test definitions that are used to test for conformance of a Desktop Agent API implementation with FDC3. + +You can find the implementation of these tests in the [FDC3 Conformance Framework](https://github.com/finos/FDC3-conformance-framework) project. + +There are currently 6 sections to the tests. Where tests apply to a particular version of FDC3, this is labelled with icons in the header, like so:   + +- [Basic Tests](Basic-Tests.md) +- [Open Tests](Open-Tests.md) +- [User Channel Tests](User-Channel-Tests.md) +- [App Channel Tests](App-Channel-Tests.md) +- [Metadata Tests](Metadata-Tests.md) +- [Intents Tests](Intents-Tests.md) diff --git a/toolbox/fdc3-conformance/User-Channel-Tests.md b/website/versioned_docs/version-2.0/api/conformance/User-Channel-Tests.md similarity index 96% rename from toolbox/fdc3-conformance/User-Channel-Tests.md rename to website/versioned_docs/version-2.0/api/conformance/User-Channel-Tests.md index 923a5332c..89f1b03cf 100644 --- a/toolbox/fdc3-conformance/User-Channel-Tests.md +++ b/website/versioned_docs/version-2.0/api/conformance/User-Channel-Tests.md @@ -1,8 +1,14 @@ +--- +id: User-Channel-Tests +sidebar_label: User Channel Tests +title: User Channel Tests +hide_title: true +--- + # User Channel Tests   _NB: User Channels were called System Channels in FDC3 1.2. The new terminology is used in this specification_ - ## Basic Broadcast | App | Step |Details | @@ -41,7 +47,7 @@ _NB: User Channels were called System Channels in FDC3 1.2. The new terminolog | A | 2.joinUserChannel |A joins the first available user channel using:
 `getSystemChannels()` Check channels are returned.
 `getUserChannels()` Check **user** channels are returned.
Call `fdc3.joinChannel()` on the first non-global channel.| | B | 3.joinUserChannel |B joins the same channel as A, via the same process in 2. | | B | 4.Broadcast | `fdc3.broadcast(
`fdc3.broadcast(
A's `fdc3.contact` object matches the one broadcast by B, and arrives on the correct listener. | +| A | 5.Receive Context | A's `fdc3.instrument` object matches the one broadcast by B, and arrives on the correct listener.
A's `fdc3.contact` object matches the one broadcast by B, and arrives on the correct listener. | - `UCFilteredUsage5`: Perform above test - `UCFilteredUsage6`: Perform above test, except B will join a _different_ channel to A. Check that you _don't_ receive anything. diff --git a/website/versioned_docs/version-2.0/fdc3-compliance.md b/website/versioned_docs/version-2.0/fdc3-compliance.md index 225b066e3..7dc3cc82d 100644 --- a/website/versioned_docs/version-2.0/fdc3-compliance.md +++ b/website/versioned_docs/version-2.0/fdc3-compliance.md @@ -70,6 +70,22 @@ FDC3 adopts the following experimental features policy: 5. Experimental features are exempted from the normal versioning and deprecation policies that govern changes to FDC3. I.e. breaking changes may be made to experimental features between versions of the Standard without a major version release. 6. The experimental designation may be removed from a feature in a minor version release (as this will be considered an additive change). +## Conformance testing + +The FDC3 Standards include a set of [definitions for conformance tests](api/conformance/Conformance-Overview) that may be used to determine if a Desktop Agent API implementation conforms to a particular Standard version, to help disambiguate complex parts of the FDC3 Standard and to enable test-driven development of a Desktop Agent implementation. + +The current set of tests focus on the Desktop Agent API and the interface to it. Tests are not yet defined for the App Directory API or Bridging API Parts of the FDC3 Standard, hence, conformance to those parts of the Standard must be determined manually. + +The FDC3 Conformance tests are implemented for JavaScript/TypeScript web applications by the [FDC3 Conformance Framework](https://github.com/finos/FDC3-conformance-framework). Desktop Agent implementors working with web interfaces (Desktop Agent Preload or Desktop Agent Proxy) can clone the conformance framework and run the tests locally to determine if their agent is compliant with the Standard. + +Once a Desktop Agent has passed the conformance tests locally, its authors can [apply for a formal certification of compliance with the Standard from FINOS](https://github.com/finos/FDC3-conformance-framework/blob/main/instructions.md). Please note the [Terms and Conditions](https://github.com/finos/FDC3-conformance-framework/blob/main/terms-conditions/FDC3-Certified-Terms.md) of the Conformance Program. + +import badge_12 from '/img/community/certified-1.2.png'; +import badge_20 from '/img/community/certified-2.0.png'; + +
`const testChannel = await fdc3.getOrCreateChannel("test-channel")` | +| A | 2.Add Context Listener |Add an _untyped_ context listener to the channel, using:
 `await testChannel.addContextListener(null, handler)`
 `testChannel.addContextListener(null, handler)` | +| B | 3.Retrieve `Channel` | Retrieve a `Channel` object representing the same 'App' channel A did (`test-channel`)| +| B | 4.Broadcast | Broadcast an `fdc3.instrument` Context to the channel with:
`testChannel.broadcast(
`const testChannel = await fdc3.getOrCreateChannel("test-channel")` | +| B | 2.Broadcast | Broadcast an `fdc3.instrument` to the channel using:
`testChannel.broadcast(
Ensure that the instrument received by A is identical to that sent by B | + +- `ACBasicUsage2` Perform above test + +## Filtered Context + +| App | Step | Details | +|-----|--------------------|-----------------------------------------------------------------| +| A | 1.Retrieve `Channel` |Retrieve a `Channel` object representing an 'App' channel called `test-channel` using:
`const testChannel = await fdc3.getOrCreateChannel("test-channel")` | +| A | 2.Add Context Listener |Add an _typed_ context listener for `fdc3.instrument`, using:
 `await testChannel.addContextListener("fdc3.instrument", handler)`
 `testChannel.addContextListener("fdc3.instrument", handler)` +| B | 3.Retrieve `Channel` |Retrieve a `Channel` object representing the same 'App' channel A did (`test-channel`)| +| B | 4.Broadcast | B broadcasts both an `fdc3.instrument` context and an `fdc3.contact` context, using:
`testChannel.broadcast(
`testChannel.broadcast(
Ensure that the fdc3.instrument received by A is identical to that sent by B
Ensure that the fdc3.contact context is NOT received. | + +- `ACFilteredContext1`: Perform above test +- `ACFilteredContext2`: Perform above test, but add listeners for both `fdc3.instrument` and `fdc3.contact` in step2. Ensure that both context objects are received. +- `ACFilteredContext3`: Perform above test, except creating a _different_ channel in app B. Check that you _don't_ receive anything (as the channels don't match). +- `ACFilteredContext4`: Perform above test, except that after creating the channel **A** creates another channel with a further _different_ channel id and adds a further context listener to it. Ensure that **A** is still able to receive context on the first channel (i.e. it is unaffected by the additional channel) and does NOT receive anything on the second channel. +- `ACUnsubscribe`: Perform above test, except that after creating the channel **A** then `unsubscribe()`s the listener it added to the channel. Check that **A** does NOT receive anything. + +### App Channel History + +| App | Step | Details | +|-----|--------------------|---------------------------------------------------------| +| A | 1.Retrieve `Channel` |Retrieve a `Channel` object representing an 'App' channel called `test-channel` using:
`const testChannel = await fdc3.getOrCreateChannel("test-channel")` | +| B | 2.Retrieve `Channel` |Retrieve a `Channel` object representing the same 'App' channel A did (`test-channel`)| +| B | 3.Broadcast |B broadcasts both the instrument context and a contact context, using:
`testChannel.broadcast(
`testChannel.broadcast(
 `await testChannel.addContextListener("fdc3.instrument", handler)`
 `testChannel.addContextListener("fdc3.instrument", handler)`
Ensure that A does NOT receive any context via these listeners (past context is only retrieved via a `getCurrentContext()` call on App channels). | +| A | 5.Retrieve Current Context | A is able to retrieve the most recent context of each context type from the `Channel` via:
`const instrument = await testChannel.getCurrentContext('fdc3.instrument')`
`const instrument = await testChannel.getCurrentContext('fdc3.contact')`
Ensure that both contexts retreived by A are identical to those sent by B| + +- `ACContextHistoryTyped`: Perform above test. +- `ACContextHistoryMultiple`: **B** Broadcasts multiple history items of both types. Ensure that only the last version of each type is received by **A**. +- `ACContextHistoryLast`: In step 5. **A** retrieves the _untyped_ current context of the channel via `const currentContext = await testChannel.getCurrentContext()`. Ensure that A receives only the very last broadcast context item _of any type_. diff --git a/website/versioned_docs/version-2.1/api/conformance/Basic-Tests.md b/website/versioned_docs/version-2.1/api/conformance/Basic-Tests.md new file mode 100644 index 000000000..24807aaea --- /dev/null +++ b/website/versioned_docs/version-2.1/api/conformance/Basic-Tests.md @@ -0,0 +1,35 @@ +--- +id: Basic-Tests +sidebar_label: Basic Tests +title: Basic Tests +hide_title: true +--- + +# Basic Tests   + +_These are some basic sanity tests implemented in the FDC3 Conformance Framework. It is expected that Desktop Agent testers will run these first before commencing the much more thorough tests in section 2 onwards._ + +- `BasicCL1`: You can create a context listener by calling `fdc3.addContextListener('fdc3.contact',
starts app B. | +| B | 2. Gather Context | `fdc.addIntentListener(‘sharedTestingIntent1’)`
Receives testContextY, matching that sent by D | + +- `SingleResolve1`: Perform above test +- `TargetedResolve1`: Use `fdc3.raiseIntent(‘aTestingIntent’, {testContextX},
`sharedTestingIntent1(testContextX)` | addIntentListener() for given intents | +| B | Raise Intent tests with Context results | `bTestingIntent(testContextY)`
`sharedTestingIntent1(testContextX, testContextY) => testContextY` | addIntentListener() for given intents | +| C | Find Intent tests (never started) | `cTestingIntent(testContextX) => testContextZ` | addIntentListener() for given intents | +| D | Find Intent tests (never started) | `sharedTestingIntent2(testContextX) => testContextZ` | addIntentListener() for given intents | +| E | Find Intent & Raise Intent with Channel result | `sharedTestingIntent2(testContextY) => channel` | addIntentListener() for given intents | +| F | Find Intent & Raise Intent with PrivateChannel result | `sharedTestingIntent2(testContextY) => channel
starts app A. | +| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent1")` to register its listener.
It then receives `testContextX`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App A's `appId` and `instanceId` set.** | + +- `2.0-RaiseIntentSingleResolve`: Perform above test +- `2.0-RaiseIntentTargetedAppResolve`: Repeat the above test, but: + - In the first step use `fdc3.raiseIntent("sharedTestingIntent1", testContextX, {"appID": "
starts app A. | +| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent")` to register its listener.
It then receives `testContextX`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App A's `appId` and `instanceId` set. | +| Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | +| A | 5. return void | A should return `void` after a short delay (e.g. 5 seconds). | +| Test | 6. receive void result | The promise received by Test from `resolution.getResult()` should resolve to void. Confirm that the promise could be retrieved before the handler function returned and that the result was received *after* the result was returned by A, NOT before. I.e. confirm that `resolution.getResult()` does NOT block until the result is returned, but rather returns a promise that can be awaited. | + +- `2.0-RaiseIntentVoidResult5secs`: Perform above test +- `2.0-RaiseIntentVoidResult0secs`: Perform above test, but A should return its result immediately (no delay). Ignore test step 6 (as there is too little time between the IntentResolution and IntentHandler completing). +- `2.0-RaiseIntentVoidResult61secs`: Perform above test, but A should return its result **after 61 seconds** (arbitrary delay to test timeout does NOT occur) + +### Raise Intent Result (Context result) + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1. Raise | `fdc3.raiseIntent("sharedTestingIntent1", testContextY)`
starts app **B**. | +| B | 2. Receive Intent & Context | After starting up, B runs `fdc3.addIntentListener("sharedTestingIntent1")` to register its listener.
It then receives `testContextY`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App B's `appId` and `instanceId` set. | +| Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | +| B | 5. return `testContextY` | B should return a `testContextY` instance after a short delay (e.g. 5 seconds). | +| Test | 6. receive context result | The promise received by Test from `resolution.getResult()` should resolve to the `testContextY` instance. Confirm that the promise could be retrieved before the handler function returned and that the result was received *after* the result was returned by B, NOT before. I.e. confirm that `resolution.getResult()` does NOT block until the result is returned, but rather returns a promise that can be awaited. | + +- `2.0-RaiseIntentContextResult5secs`: Perform the above test. +- `2.0-RaiseIntentContextResult0secs`: Perform the previous test but B should return its result immediately (no delay). +- `2.0-RaiseIntentContextResult61secs`: As above, but B should return its result **after 61 seconds** (arbitrary delay to test timeout does NOT occur) + +### Raise Intent Result (Channel results) + +| App | Step | Details | +|-------|-----------------------|---------------------------------------------------------------------------------------------------| +| Test | 1. Raise Intent | Test raises an intent with `fdc3.raiseIntent("sharedTestingIntent2", testContextY, {appId: "
starts app E. | +| E | 2. Receive Intent & Context | After starting up, E runs `fdc3.addIntentListener("sharedTestingIntent2")` to register its listener.
It them receives `testContextY`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App E's `appId` and `instanceId` set. | +| Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | +| E | 5. return Channel | E should retrieve a Channel object via `fdc3.getOrCreateChannel("someChannelName")` and return it immediately. | +| Test | 6. receive Channel result | The promise received by Test from `resolution.getResult()` should resolve to a `Channel` object with the expected id. Confirm that the `type` of the Channel object is "app". +| Test | 7. addContextListener | Add a context listener to the Channel object via `channelObj.addContextListener("testContextZ", handler)` | +| E | 8. broadcast context | After a short delay (of a few seconds) E should broadcast a `testContextZ` context object over the channel, including an `id` field with a unique identifier set (e.g. a uuid). | +| Test | 9. receive context | Test should receive the context broadcast by E and confirm that it contains the expected `id` value. | + +- `2.0-RaiseIntentChannelResult`: Perform the above test +- `2.0-RaiseIntentPrivateChannelResult`: Perform the above test, but: + - Substitute app F throughout - which returns a PrivateChannel result instead of channel. + - At step 5, the PrivateChannel should be created via`fdc3.createPrivateChannel()`. + - At step 6 confirm that the type of the channel is "private". + +### PrivateChannels cannot be accessed as app channels + +| App | Step | Details | +|-------|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1. Create a private channel | Test creates a PrivateChannel with `const privChan = await fdc3.createPrivateChannel()`. Confirm that the Channel has an `id`. +| Test | 2. Confirm private channel `id` is unique | Test creates a second PrivateChannel with `const privChan = await fdc3.createPrivateChannel();`. Confirm that the Channel has an `id` and that it is distinct from the first channel created. | +| Test | 3. Retrieve as app channel | Attempt to retrieve the channels as App Channels with `const appChan = await fdc3.getOrCreateChannel(privChan.id)` this should fail with `ChannelError.AccessDenied` | +| Test | 4. Raise Intent & await result | Start app J and pass it the id of the second PrivateChannel with `fdc3.raiseIntent("privateChannelIsPrivate", privateChannelDetails)`, where the context object contains the id of the channel to attempt to retrieve. An IntentResolution should be returned and App J should start. Wait for a result to be returned via `await resolution.getResult()`. +| J | 5. Receive Intent & Context | J should add an Intent Listener and receive the context with `fdc3.addIntentListener("privateChannelIsPrivate", handler)` | +| J | 6. Retrieve as app channel | J should attempt to retrieve the channel as an App Channel by `id` with `const appChan = await fdc3.getOrCreateChannel("
starts app K. | +| K | 2. Receive Intent & Context | After starting up, K runs `fdc3.addIntentListener("kTestingIntent")` to register its listener.
It them receives `testContextX`, matching that sent by Test | +| Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App K's `appId` and `instanceId` set. | +| Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | +| K | 5. Create PrivateChannel and setup event listeners | K should create a `PrivateChannel` object via `const privChan = await fdc3.createPrivateChannel()`,
it should then add listeners for the 3 events offered + a context listener via:
- `const listener1 = await privChan.onAddContextListener(handler1);`
- `const listener2 = await privChan.onUnsubscribe(handler2);`
- `const listener3 = await privChan.onDisconnect(handler3);`
- `const listener4 = await privChan.addContextListener("testContextX", handler4)`
it should then return the `PrivateChannel`. | +| Test | 6. receive PrivateChannel | The promise received by Test from `resolution.getResult()` should resolve to a `PrivateChannel` object. Confirm that the `type` of the Channel object is "private". +| Test | 7. addContextListener | Test should add a context listener to the PrivateChannel object via `const listener1 = privChan.addContextListener("testContextZ", handler)` | +| K | 8. Receive event & broadcast context | The `onAddContextListener` handler (`listener1`) added in step 5 should fire after Test adds its listener. Once it has, K should broadcast a short stream of `testContextZ` objects, with consecutive integer values in them (e.g. 1-5). | +| Test | 9. Unsubscribe listener | Test should confirm receipt of the expected context objects, in the expected order, broadcast by K. It should then remove its context listener with `listener1.unsubscribe().` | +| K | 10. Receive unsubscribe event | The event handler registered by K via `onUnsubscribe` should fire. If it does not and the test moves to a subsequent step, K should indicate this to the test runner (failing the test).| +| Test | 11. Broadcast context | Test should broadcast at least one `testContextX` object via the PrivateChannel (back to K). | +| K | 12. Receive context | K should confirm receipt of the expected context. If it does not and the test moves to a subsequent step K should indicate this to the test runner (failing the test).| +| Test | 13. re-run addContextListener | Test should (again) add a context listener to the PrivateChannel object via `const listener2 = privChan.addContextListener("testContextZ", handler)` | +| K | 14. Receive event & broadcast context | The `onAddContextListener` handler added in step 5 should (again) fire after Test adds its listener. Once it has, K should again broadcast a short stream of `testContextZ` objects, with consecutive integer values in them (e.g. 6-10). | +| Test | 15. Disconnect | Test should (again) confirm receipt of the expected context objects, in the expected order, broadcast by K. It should then disconnect from the channel with [`privChan.disconnect().`](https://fdc3.finos.org/docs/api/ref/PrivateChannel#disconnect) | +| K | 16. Receive events & cleanup | The `onUnsubscribe` handler added in step 5 should (again) fire after Test calls `privChan.disconnect()`. Subsequently, the `onDisconect` handler also added in step 5 should fire. Once it has, K can unsubscribe its listeners, indicate to the test runner that all steps were completed and close. | + +- `2.0-PrivateChannelsLifecycleEvents`: Perform the above test. + +### Resolving Ambiguous Intents + +FDC3 Desktop Agent MUST provide a method of resolving ambiguous intents (i.e. those that might be resolved by multiple applications) or unspecified intents (calls to raiseIntentForContext that return multiple options). This is often accomplished by providing a user interface allowing the user to select the desired target application or intent and application. + +As the methods of resolving ambiguous intents are often user interactive, it is either difficult or impossible to implement an automated test for this. Hence, manual tests should be performed as a final step in a conformance test. These tests are based on the same applications defined for and used in other intent tests - however a separate manual test app should be provided to enable the test. + +| App | Step | Details | +|---|---|---| +| Test | 1. Raise Ambiguous Intent | `fdc3.raiseIntent("sharedTestingIntent2", testContextY)` | +| User | 2. Chooser Interaction | A method of resolving the ambiguous request is provided (such as a User Interface allowing the user to choose an application or instance) for choosing one of `E`,`F`,`G`,`H` and `I`. | + +- `2.0-ResolveAmbiguousIntentTarget`: Perform above steps to invoke intent resolution for an unspecified target with multiple options. Confirm that test is able to complete successfully. + +| App | Step | Details | +|---|---|---| +| Test | 1. Raise Ambiguous Intent | `fdc3.raiseIntentForContext(testContextY)` | +| User | 2. Chooser Interaction | Chooser Interaction | A method of resolving the ambiguous request is provided (such as a User Interface allowing the user to choose an application or instance) for choosing one of `E`,`F`,`G`,`H` and `I`. | + +- `2.0-ResolveAmbiguousContextTarget`: Perform above steps to invoke intent resolution for an unspecified target with multiple options. Confirm that test is able to complete successfully. + +| App | Step | Details | +|---|---|---| +| Test | 1. Open 4 Apps | Use `fdc3.open()` to open 2 instances of App `E` and 2 instances of `F`. | +| Test | 2. Raise Ambiguous Intent | `fdc3.raiseIntent("sharedTestingIntent2", testContextY)` | +| User | 3. Chooser Interaction | Chooser Interaction | A method of resolving the ambiguous request is provided (such as a User Interface allowing the user to choose an application or instance) for choosing one of `E (1)`,`F (1)`,`E (2)`,`F (2)` and options to open `G`, `H` and `I` | + +- `2.0-ResolveAmbiguousIntentTargetMultiInstance`: Perform above steps to invoke intent resolution for an unspecified target with multiple options. Confirm that test is able to complete successfully. + +| App | Step | Details | +|---|---|---| +| Test | 1. Open 4 Apps | Use `fdc3.open()` to open 2 instances of App `E` and 2 instances of `F`. | +| Test | 2. Raise Ambiguous Intent | `fdc3.raiseIntentForContext(testContextY)` | +| User | 3. Chooser Interaction | Chooser Interaction | A method of resolving the ambiguous request is provided (such as a User Interface allowing the user to choose an application or instance) for choosing one of `E (1)`,`F (1)`,`E (2)`,`F (2)` and options to open `G`, `H` and `I` | + +- `2.0-ResolveAmbiguousContextTargetMultiInstance`: Perform above steps to invoke intent resolution for an unspecified target with multiple options. Confirm that test is able to complete successfully. diff --git a/website/versioned_docs/version-2.1/api/conformance/Metadata-Tests.md b/website/versioned_docs/version-2.1/api/conformance/Metadata-Tests.md new file mode 100644 index 000000000..456b4bff3 --- /dev/null +++ b/website/versioned_docs/version-2.1/api/conformance/Metadata-Tests.md @@ -0,0 +1,68 @@ +--- +id: Metadata-Tests +sidebar_label: Metadata Tests +title: Metadata Tests +hide_title: true +--- + +# Metadata & Instance Test Cases + +You will need to pre-populate the AppDirectory with the following items: + +| App | Required Metadata | +|-----|------------------------------------------| +| A | Generic AppD Record which contains at least the following fields:
- `name`
- `version`
- `title`
- `tooltip`
- `description`
- `icons` (`Array
- `screenshots` (`Array
- `interop.intents.listensFor` (`aTestingIntent` with at least context type `testContextX`) | + +## Retrieve `AppMetadata`  + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1.getAppMetadata | Retrieve metadata for the configured app A with
`const metadata1 = await fdc3.getAppMetadata({appId: "
`const appIdentifier1 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId`. | +| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | +| Test | 3.getAppMetadata1 | Retrieve metadata for the first instance of the app with
`const metadata1 = fdc3.getAppMetadata(appIdentifier1)` | +| Test | 4.Confirm1 | Compare the `AppMetadata` object to the expected definition for the fields provided above during setup and ensure that the metadata matches. | +| Test | 5.getAppMetadata2 | Retrieve metadata for the second instance of the app with
`const metadata2 = fdc3.getAppMetadata(appIdentifier2)` | +| Test | 6.Confirm2 | An `instanceId` should be provided, confirm that it matches the one in `appIdentifier2` | + +- `AppInstanceMetadata`: Perform the above steps + +## Finding Instances  + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1.Open1 | Open the first instance of App A using
`const appIdentifier1 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId`. | +| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: "
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | +| Test | 3.FindInstances | Retrieve details of open instances of app A with
`let instances = await fdc3.findInstances({appId: "
confirm that both `appIdentifier1` and `appIdentifier2` are both present in the array. | +| Test | 4.RaiseIntent | Use `appIdentifier1` to raise an intent and target that instance, with
`const resolution = fdc3.raiseIntent("aTestingIntent", {"type": "testContextX"}, appIdentifier1)` | +| Test | 5.Confirm1 | Check that `resolution.source` matches `appIdentifier1` | +| A | 6.ConfirmReceipt | Ensure that the instance of app A represented by `appIdentifier1` received the raised intent | + +- `FindInstances`: Perform the above steps + +## Getting Info For The Agent + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1.getInfo |Retrieve the `ImplementationMetadata` for the DesktopAgent with
-  `let implMetadata = fdc3.getInfo()`
-  `fdc3.getInfo().then((implMetadata) => { subsequent steps }`
**Note that the use of `then` is deliberate and intended to confirm that a promise returned (as this function switched from synchronous to asynchronous in 2.0)**| +| Test | 2.CheckVersion | Check that the `fdc3Version` variable is present and at or greater than:
-  1.2
-  2.0
(which you can do with the [`versionIsAtLeast` function from FDC3's Methods.ts](https://github.com/finos/FDC3/blob/add64f8302c6dcdc8437cf0e245101e927b69ec2/src/api/Methods.ts#L207):
`const isFDC3v2 = versionIsAtLeast(implMetadata, "2.0")` | +| Test | 3.CheckProvider | Check that the `provider` variable is present and not an empty string | +| Test | 4.CheckFeatures |  Check that the `optionalFeatures`, `optionalFeatures.OriginatingAppMetadata` and `optionalFeatures.UserChannelMembershipAPIs` variables are all present and that the latter two provide boolean values | + +-   `GetInfo1`: Perform the above steps + +| App | Step | Details | +|-----|----------------|---------------------------------------------------------------------------------------------------| +| Test | 1.Open1 | Start an instance of App A with
`const appIdentifier1 = await fdc3.open({appId: "
retrieve its `AppIdentifier` with instance details. Confirm that the `AppIdentifier` contains both an `appId` and `instanceId` | +| A | 2.getInfo | Retrieve the `ImplementationMetadata` for the DesktopAgent with:
`fdc3.getInfo().then((implMetadata) => { ... subsequent steps ...}`
This should include `AppMetadata` for the retrieving app. | +| A + Test | 3.Confirm | Check that `implMetadata.appMetadata` contains an `appId` and `instanceId` matching that retrieved in the first step (will require transmission of the details from A to Test or vice-versa). Also compare the `AppMetadata` object to the expected definition for the fields provided above during setup and ensure that the metadata matches. | + +-  `GetInfo2`: Perform the above steps. diff --git a/website/versioned_docs/version-2.1/api/conformance/Open-Tests.md b/website/versioned_docs/version-2.1/api/conformance/Open-Tests.md new file mode 100644 index 000000000..85e8f0aa6 --- /dev/null +++ b/website/versioned_docs/version-2.1/api/conformance/Open-Tests.md @@ -0,0 +1,54 @@ +--- +id: Open-Tests +sidebar_label: Open Tests +title: Open Tests +hide_title: true +--- + +# Open Tests + +## A Opens B + +| App | Step | Description | +|-----|-----------------|----------------------------------------------------------| +| A | 1. Opening App | App A calls a function (see below) to open a second app, B | +| A | 2. Check Metadata | Ensure that the correct app was opened | + +- `AOpensB1`:  **A** uses `fdc3.open(‘app B Name’)` +- `AOpensB2`:  **A** uses `fdc3.open({name: “
 `fdc3.open` returns a promise that rejects with an Error with the message "App Not Found" | + +- `AFailsToOpenB1`:  **A** uses `fdc3.open(‘non existent app’)` +- `AFailsToOpenB2`:  **A** uses `fdc3.open({name: “non existent app”})` +- `AFailsToOpenB3`: **A** uses an `AppMetadata` or `AppIdentifier` to open B, via: + -  `fdc3.open({name: “non existent app”, appId: “non existent app”})` + -  `fdc3.open({appId: “
`fdc3.addContextListener(null, handler)`
B receives an `fdc3.instrument` Context Object matching that passed to the `fdc3.open() call made by A | + +- `AOpensBWithContext1`:  **A** uses `fdc3.open(‘app B Name',
 A `Listener` object is returned
 A promise resolving a `Listener` object is returned
Check that this has an `unsubscribe` method. | +| A | 2.joinUserChannel |A joins the first available (non-global) user channel. The available Channels are retrieved with:
 `fdc3.getSystemChannels()` _Check channels are returned._
 `fdc3.getUserChannels()`
The first channel (that does not have the id 'global') is joined with:
 `fdc3.joinChannel(
 `fdc3.joinUserChannel(
 Check a `void` promise is returned. | +| A | 5.Receive Context | A receives the instrument object, matching the one broadcast by B. | + +- `UCBasicUsage1` Perform above test +- `UCBasicUsage2` Perform steps in order: 2,1,3,4,5 to confirm that the order of `joinUserChannel` and `addContextListener` calls doesn't matter +- `UCBasicUsage3` Perform steps in order: 3,4,1,2,5 to confirm that the current context is automatically received on joining a channel. +- `UCBasicUsage4` Perform steps in order: 3,4,2,1,5 to confirm that the current context is automatically received on adding a context listener to an already joined a channel. + +## Filtered Broadcast + +| App | Step |Details | +|-----|--------------------|----------------------------------------------------------------------------------| +| A | 1.addContextListener |A adds a `fdc3.instrument` _typed_ Context Listener using `addContextListener("fdc3.instrument", handler)`.
 A `Listener` object is returned
 A promise resolving a `Listener` object is returned
Check that this has an `unsubscribe` method.| +| A | 2.joinUserChannel |A joins the first available user channel using:
 `getSystemChannels()` Check channels are returned.
 `getUserChannels()` Check **user** channels are returned.
Call `fdc3.joinChannel()` on the first non-global channel.| +| B | 3.joinUserChannel |B joins the same channel as A, via the same process in 2. | +| B | 4.Broadcast | B broadcasts:
1.`fdc3.broadcast(
2. `fdc3.broadcast()`
 Check a `void` promise is returned. | +| A | 5.Receive Context | A receives the `fdc3.instrument` object, matching the one broadcast by B.
Check that the `fdc3.contact` is NOT received. | + +- `UCFilteredUsage1` Perform above test +- `UCFilteredUsage2` Perform steps in order: 2,1,3,4,5 +- `UCFilteredUsage3` Perform steps in order: 3,4,1,2,5 +- `UCFilteredUsage4` Perform steps in order: 3,4,2,1,5 + +## Broadcast With Multiple Listeners + +| App | Step | Details | +|-----|--------------------|-------------------------------------------------------------------------------------------------------------| +| A | 1.addContextListeners | A sets up two Context Listeners. One for `fdc3.instrument` and one for `fdc3.contact` by calling: `addContextListener ("fdc3.instrument", handler)`
`addContextListener ("fdc3.contact", handler)`
 A `Listener` object is returned for each.
 A promise resolving a `Listener` object is returned for each.
Check that this has an `unsubscribe` method for each. | +| A | 2.joinUserChannel |A joins the first available user channel using:
 `getSystemChannels()` Check channels are returned.
 `getUserChannels()` Check **user** channels are returned.
Call `fdc3.joinChannel()` on the first non-global channel.| +| B | 3.joinUserChannel |B joins the same channel as A, via the same process in 2. | +| B | 4.Broadcast | `fdc3.broadcast(
`fdc3.broadcast(
A's `fdc3.contact` object matches the one broadcast by B, and arrives on the correct listener. | + + - `UCFilteredUsage5`: Perform above test + - `UCFilteredUsage6`: Perform above test, except B will join a _different_ channel to A. Check that you _don't_ receive anything. + - `UCFilteredUsageChange`: Perform above test, except that after joining, **A** changes channel to a _different_ channel via a further call to `fdc3.joinUserChannel`. Check that **A** does NOT receive anything. + - `UCFilteredUsageUnsubscribe`: Perform above test, except that after joining, **A** then `unsubscribe()`s from the channel using the `listener.unsubscribe` function. Check that **A** does NOT receive anything. + - `UCFilteredUsageLeave`: Perform above test, except that immediately after joining, **A** _leaves the channel_, and so receives nothing. + - `UCFilteredUsageNoJoin`: Perform the above test, but skip step 2 so that **A** does NOT join a channel. Confirm that the _current channel_ for **A** is NOT set before continuing with the rest of the test. **A** should receive nothing. diff --git a/website/versioned_docs/version-2.1/fdc3-compliance.md b/website/versioned_docs/version-2.1/fdc3-compliance.md index 64f242828..7cfcbd1d6 100644 --- a/website/versioned_docs/version-2.1/fdc3-compliance.md +++ b/website/versioned_docs/version-2.1/fdc3-compliance.md @@ -70,6 +70,26 @@ FDC3 adopts the following experimental features policy: 5. Experimental features are exempted from the normal versioning and deprecation policies that govern changes to FDC3. I.e. breaking changes may be made to experimental features between versions of the Standard without a major version release. 6. The experimental designation may be removed from a feature in a minor version release (as this will be considered an additive change). +## Conformance testing + +The FDC3 Standards include a set of [definitions for conformance tests](api/conformance/Conformance-Overview) that may be used to determine if a Desktop Agent API implementation conforms to a particular Standard version, to help disambiguate complex parts of the FDC3 Standard and to enable test-driven development of a Desktop Agent implementation. + +The current set of tests focus on the Desktop Agent API and the interface to it. Tests are not yet defined for the App Directory API or Bridging API Parts of the FDC3 Standard, hence, conformance to those parts of the Standard must be determined manually. + +:::info +As FDC3 2.1 does not introduce changes to the Desktop Agent API, the conformance test set for FDC3 2.0 remains current for this version. Please see the [FDC3 2.1 Changelog entry](https://github.com/finos/FDC3/blob/main/CHANGELOG.md#fdc3-standard-21---2023-09-13) for more details. +::: + +The FDC3 Conformance tests are implemented for JavaScript/TypeScript web applications by the [FDC3 Conformance Framework](https://github.com/finos/FDC3-conformance-framework). Desktop Agent implementors working with web interfaces (Desktop Agent Preload or Desktop Agent Proxy) can clone the conformance framework and run the tests locally to determine if their agent is compliant with the Standard. + +Once a Desktop Agent has passed the conformance tests locally, its authors can [apply for a formal certification of compliance with the Standard from FINOS](https://github.com/finos/FDC3-conformance-framework/blob/main/instructions.md). Please note the [Terms and Conditions](https://github.com/finos/FDC3-conformance-framework/blob/main/terms-conditions/FDC3-Certified-Terms.md) of the Conformance Program. + +import badge_12 from '/img/community/certified-1.2.png'; +import badge_20 from '/img/community/certified-2.0.png'; + +