Add conformance tests into docs

CHANGELOG.md

@@ -20,6 +20,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Typescript definitions for Desktop Agent Communication Protocol (DACP). These constitute the internal "wire protocol" that the "@finos/fdc3" library uses to communicate with Browser-Resident DAs. ([#1191](https://github.com/finos/FDC3/pull/1191))
 * Typescript definitions for Web Connection Protocol (WCP). These constitute the messages used to establish connectivity between "@finos/fdc3" and a Browser-Resident DA. ([#1191](https://github.com/finos/FDC3/pull/1191))
 * Added support for broadcast actions to the `fdc3.action` context type, allowing an Action to represent the broadcast of a specified context to an app or user channel. ([#1368](https://github.com/finos/FDC3/pull/1368))
+* Added conformance tests into the FDC3 API documentation in the current version and backported into 2.0 and 2.1. Removed outdated 1.2 conformance tests (which are preserved in the older 2.0 and 2.1 versions). ([#1417](https://github.com/finos/FDC3/pull/1417)).
 
 ### Changed
 

docs/api/conformance/App-Channel-Tests.md

@@ -0,0 +1,62 @@
+---
+id: App-Channel-Tests
+sidebar_label: App Channel Tests
+title: App Channel Tests
+hide_title: true
+---
+
+# App Channel Tests  
+<!-- markdownlint-disable MD033 -->
+
+## Basic Broadcast
+
+| App | Step               | Details                                                                    |
+|-----|--------------------|----------------------------------------------------------------------------|
+| A   | 1.Retrieve `Channel`    |Retrieve a `Channel` object representing an 'App' channel called `test-channel` using: <br />`const testChannel = await fdc3.getOrCreateChannel("test-channel")` |
+| A   | 2.Add Context Listener |Add an _untyped_ context listener to the channel, using: <br /> !`await 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: <br />`testChannel.broadcast(<fdc3.instrument context>)`|
+| A   | 5.Receive Context    | The handler added in step 2 will receive the instrument context. Ensure that the instrument received by A is identical to that sent by B.  |
+
+- `ACBasicUsage1` Perform above test.
+
+## Current Context
+
+| App | Step               | Details                                                                    |
+|-----|--------------------|----------------------------------------------------------------------------|
+| B   | 1.Retrieve `Channel` |Retrieve a `Channel` object representing an 'App' channel called `test-channel` using: <br />`const testChannel = await fdc3.getOrCreateChannel("test-channel")` |
+| B   | 2.Broadcast          | Broadcast an `fdc3.instrument` to the channel using: <br />`testChannel.broadcast(<fdc3.instrument context>)`|
+| A   | 3.Retrieve `Channel`   |Retrieve a `Channel` object representing the same 'App' channel B did (`test-channel`)|
+| A   | 4.Retrieve Current Context    | A gets the _current context_ of the user channel. via:  `await testChannel.getCurrentContext()` <br />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: <br />`const testChannel = await fdc3.getOrCreateChannel("test-channel")` |
+| A   | 2.Add Context Listener |Add an _typed_ context listener for `fdc3.instrument`, using: <br />`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: <br /> `testChannel.broadcast(<fdc3.instrument context>)` <br /> `testChannel.broadcast(<fdc3.contact context>)`|
+| A   | 5.Receive Context    | An fdc3.instrument context is received by the handler added in step 2.<br />Ensure that the fdc3.instrument received by A is identical to that sent by B<br />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: <br />`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: <br /> `testChannel.broadcast(<fdc3.instrument context>)` <br /> `testChannel.broadcast(<fdc3.contact context>)` |
+| A   | 4.Add Context Listener| A adds a context listener to the channel _after_ B has completed all its broadcasts, via: <br />`await testChannel.addContextListener("fdc3.instrument", handler)` <br /> 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: <br />`const instrument = await testChannel.getCurrentContext('fdc3.instrument')`<br />`const instrument = await testChannel.getCurrentContext('fdc3.contact')`<br />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_.

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
+<!-- markdownlint-disable MD033 -->
+
+_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',<handler>)`.  A `Listener` object is returned and can be used to remove the listener again by calling its `unsubscribe` function.
+- `BasicCL2`: You can create an **unfiltered** context listener by calling `fdc3.addContextListener(null,<handler>)`.  A `Listener` object is returned and can be used to remove the listener again by calling its `unsubscribe` function.
+- `BasicIL1`: You can create an intent listener by calling `fdc3.addIntentListener(<intent name>,<handler>)`. A `Listener` object is returned and can be used to remove the listener again by calling its `unsubscribe` function.
+- `BasicGI1`: An application can retrieve an `ImplementationMetadata` object to find out the version of FDC3 it is using and the provider details by calling:
+  - `await fdc3.getInfo()`
+- `BasicAC1`: An application can retrieve a named 'App' channel via the `fdc3.getOrCreateChannel(<name>)` function. The `Channel` object returned conforms to the defined interface.
+- `BasicUC1`: An application can query the available user/system channels, which are returned as an array of `Channel` Objects conforming to the defined interface.  The API call is:
+  - `await fdc3.getUserChannels()`
+- `BasicJC1`: The application should be able to join one of the user/system channels with the channel's id.  Having done so, the current channel should NOT be null, and be set for the application _to the channel for the id given_.  After you leave the current channel, it should go back to being `null`.
+  - The channel is joined with:
+    - `fdc3.joinUserChannel(<channelId>)`
+  - A `Channel` object representing the current channel is retrieved with:
+    - `fdc3.getCurrentChannel()` to get the current channel.
+  - The channel is left with:
+    - `fdc3.leaveCurrentChannel()`
+- `BasicRI1`: The application should be able to raise an intent by invoking:
+  - `fdc3.raiseIntent(<intent name>)`
+  - A promise should be returned.
+- `BasicRI2`: The application should be able to raise an intent for some item of context by invoking:
+  - `fdc3.raiseIntentForContext(<context>)`
+  - A promise should be returned.