Add conformance tests into docs

CHANGELOG.md

@@ -23,6 +23,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added utility functions `isStandardContextType(contextType: string)`, `isStandardIntent(intent: string)`,`getPossibleContextsForIntent(intent: StandardIntent)`. ([#1139](https://github.com/finos/FDC3/pull/1139))
 * Added support for event listening outside of intent or context listnener. Added new function `addEventListener`, type `EventHandler`,  enum `FDC3EventType` and interfaces `FDC3Event` and `FDC3ChannelChangedEvent`. ([#1207](https://github.com/finos/FDC3/pull/1207))
 * Added new `CreateOrUpdateProfile` intent. ([#1359](https://github.com/finos/FDC3/pull/1359))
+* 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>)`|
+| 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>)`|
+| 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>)` <br /> `testChannel.broadcast(<fdc3.contact>)`|
+| 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>)` <br /> `testChannel.broadcast(<fdc3.contact>)` |
+| 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 contact = 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,23 @@
+---
+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`: A context listener can be created for a specific context type 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`: An **unfiltered** context listener can be created 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`: An intent listener can be created for a specific intent by calling `fdc3.addIntentListener(<intentName>,<handler>)`. A `Listener` object is returned and can be used to remove the listener again by calling its `unsubscribe` function.
+- `BasicGI1`: An `ImplementationMetadata` object can be retrieved, to find out the version of FDC3 that is in use along with details of the provider, by calling:
+  - `await fdc3.getInfo()`.w The FDC3 version should match the API version being tested for conformance.
+- `BasicAC1`: A named 'App' channel can be retrieved via the `fdc3.getOrCreateChannel(<name>)` function. The `Channel` object returned conforms to the defined interface.
+- `BasicUC1`: The list available user/system channels can be retrieved as an array of `Channel` Objects conforming to the defined interface.  The API call is:
+  - `await fdc3.getUserChannels()`
+- `BasicJC1`: A user/system channel can be joined with the with the channel's id by calling `fdc3.joinUserChannel(<channelId>)`.  Having done so, the current channel, retrieved by calling `fdc3.getCurrentChannel()` should NOT be null and should match _the channel id given_.  After leaving the current channel by calling `fdc3.leaveCurrentChannel()`, it should go back to being `null`.
+- `BasicRI1`: A specified intent can be raised by invoking `fdc3.raiseIntent(<intent name>, <context>)`. A promise should be returned.
+- `BasicRI2`: An intent can be raised for some item of context by invoking: `fdc3.raiseIntentForContext(<context>)`. A promise should be returned.