The TKW (ToolKit Workbench) Simulators are tools to assist with developing and assuring a solution to meet the Booking Standard. There are two tools in the suite, to support the Provider and Consumer functionality, and they can utilised locally or in the dedicated environments – OpenTest or INT. When utlised within the dedicated environments they are supported by the other services – DoS, SDS and SSP – to replicate as near to like-live scenarios as possible.
What are they?
Fundamentally, the TKW Simulators are (Docker) containers which neatly package all required resources, irrespective of the environment they are run on. There are two containers (Provider and Consumer) to replicate the different aspects of functionality and links to each of them can be found under the Resources section below.
Resources
Resources required to understand and run the TKW Simulators
Docker
Docker download
TKW Simulators Downloads
Deploying
When starting to build a solution the TKW Simulators can be deployed locally, to validate the requests and responses made by either Providers or Consumers. This section will explain how to deploy and later sections will go on to explain how to use the tool.
Windows
Click to see step-by-step setup guide
Mac
Click to see step-by-step setup guide
Using TKW Simulators
The TKW Provider and Consumer Simulators will interact with each. It is advisable to set them up like that initially to ensure they’re working before proceeding to use them to test any other implementation.
The TKW Simulators can be run locally or within the dedicated Path-to-Live environments (OpenTest, INT). You will need to register via a Portal (See Appendix8) to utilise their functionality in these environments. An additional benefit of utilising the TKW tools in this way is the ability to prove end-to-end functionality with the core infrastructure components (SDS and SSP).
This section will further explain how the tools are intended to be used and their functionality.
Consumer
The TKW Consumer Simulator will test a Provider endpoint and is capable of running in three modes –
- All test suites (see Test Suites section below)
- e.g. ./run_consumer_simulator.sh <toAsid>
- Single test suite (see Test Suites section below)
- e.g. ./run_consumer_simulator.sh <toAsid> [A S B C]
- Single test within a test suite (see Appendix7 for individual test names)
- e.g. ./run_consumer_simulator.sh -s <toAsid> <TestName>
The simulator is instantiated by running either a batch (Windows) or shell (Mac) file, the mode being defined by the parameters assigned. It will perform the requested tests and output a validation report for review under ‘..\auto_tests\<ASID>'.
There are logs of activity of the Consumer Simulator under ‘..\autotest_logs’.
NB: To point the TKW Consumer Simulator at the Provider solution to be tested edit the <ASID>.sh file in the ..\endpoint_configs folder, editing the ‘to_ep=<provider solution endpoint>’ value.
Test Suites
To run a single test suite, use the Initial value when invoking the Consumer Simulator.
| Initial | Test Suite |
|---|---|
| A | cApability |
| S | Search for free slots |
| B | Book appointment |
| C | Cancel appointment |
Provider
The TKW Provider Simulator is capable of testing a Consumer solution. As with any Provider system solution, it is passive and waits to accept requests.
Once the container is up and running, reporting ‘ITK Testbench ready’, requests can be sent to it. The supplier’s Consumer solution can be directed to the Provider Simulator, based on the address it was configured to listen via the Docker compose file - docker-compose_provider_simulator.yml.
The Provider Simulator can also be tested using an API Test Tool such as Postman. A collection of all the requests which can be made to the Provider Simulator have been documented and can be imported into the Postman tool to assist seeing what the requests contain and envisage the eventual workflows.
A validation report of activity sent to the Provider Simulator resides under ‘..\all_evidence\<ASID>’ and logs of activity is recorded in ‘..\logs’.
Support
For any issues or assistance with the TKW Simulators you can contact the Team
Assuring with TKW
Another key feature of the TKW Simulator Tools is to assist with the self assurance process and provide the required evidence for the SCAL submission. Once the solution is complete, depending on whether it is fulfilling Provider or Consumer functionality, it can be configured to make or receive requests from the corresponding Simulator Tool. The Tool will record and collate the necessary evidence to be attached as part of the assurance process, as detailed in Using TKW Simulators section above.
Appendices
Click to expand appendices
Appendix1 – Docker Compose file for Provider Simulator (Windows)
version: '2.0'
services:
tkw_uec_provider_simulator:
ports:
- '4434:4434'
volumes:
- 'C:/Users/xxx/AppData/Local/Temp/assurance/scratch/data:/home/service/data'
- 'C:/Users/xxx/AppData/Local/Temp/assurance/scratch:/home/service/fhir'
image: 'nhsdigitalmait/tkw_uec_provider_simulator:0.5'
Appendix2 – Docker Compose file for Consumer Simulator (Windows)
#
# docker-compose file supporting a docker stack comprised of a
# 111_uec consumer simulator suite instance
#
version: "3"
services:
tkw_uec_consumer_simulator:
image: nhsdigitalmait/tkw_uec_consumer_simulator:0.5
environment:
- TZ=Europe/London
network_mode : "host"
volumes:
# <host path to mount> : <mount point within docker>
# auto_tests folder
- 'C:/Users/xxx/AppData/Local/Temp/config/FHIR_111_UEC/autotest_config/auto_tests:/home/service/TKW/config/FHIR_111_UEC/autotest_config/auto_tests'
# endpoint_configs folder
- 'C:/Users/xxx/AppData/Local/Temp/config/FHIR_111_UEC/autotest_config/endpoint_configs:/home/service/TKW/config/FHIR_111_UEC/autotest_config/endpoint_configs'
# autotest logs folder
- 'C:/Users/xxx/AppData/Local/Temp/config/FHIR_111_UEC/autotest_config/autotest_logs:/home/service/TKW/config/FHIR_111_UEC/autotest_config/autotest_logs'
Appendix3 – Batch file to instantiate the Consumer Simulator
REM
REM invokes execution of tkw_uec_consumer_simulator in autotest mode to test Emeregncy Booking providers
REM
docker-compose -f docker-compose_consumer.yml run --rm tkw_uec_consumer_simulator %*
Appendix4 – Docker Compose file for Provider Simulator (Mac)
version: '2.0'
services:
tkw_uec_provider_simulator:
ports:
- '4434:4434'
volumes:
- '/Users/xxx/Work/NHS-D/UEC/Testing/Data:/home/service/data'
- '/Users/xxx/Work/NHS-D/UEC/Testing/Data:/home/service/fhir'
image: 'nhsdigitalmait/tkw_uec_provider_simulator:0.5'
Appendix5 – Docker Compose file for Consumer Simulator (Mac)
#
# docker-compose file supporting a docker stack comprised of a
# 111_uec consumer simulator (provider test suite) instance
#
version: "3"
services:
tkw_uec_consumer_simulator:
image: nhsdigitalmait/tkw_uec_consumer_simulator:0.5
environment:
- TZ=Europe/London
network_mode : "host"
volumes:
# <host path to mount> : <mount point within docker>
# auto_tests folder
- /Users/xxx/Work/NHS-D/UEC/Testing/Config/FHIR_111_UEC/autotest_config/auto_tests:/home/service/TKW/config/FHIR_111_UEC/autotest_config/auto_tests
# endpoint_configs folder
- /Users/xxx/Work/NHS-D/UEC/Testing/Config/FHIR_111_UEC/autotest_config/endpoint_configs:/home/service/TKW/config/FHIR_111_UEC/autotest_config/endpoint_configs
# autotest logs folder
- /Users/xxx/Work/NHS-D/UEC/Testing/Config/FHIR_111_UEC/autotest_config/autotest_logs:/home/service/TKW/config/FHIR_111_UEC/autotest_config/autotest_logs
Appendix6 - Endpoint configuration file example (default)
# Autotest endpoint config file
#
# to local clear
to_ep=http://localhost:4434/STU3
#to_ep=http://localhost/STU3
# to local secure
#to_ep=https://localhost:4431/STU3
# to local via reverse proxy
#to_ep=http://192.168.1.112/STU3
# defaults
#toasid=200000000359
#fromasid=200000000359
#sendtls=No
#truststore=/TKW_ROOT/config/FHIR_111_UEC/autotest_config/endpoint_configs/certs/opentest.jks
#keystore=/TKW_ROOT/config/FHIR_111_UEC/autotest_config/endpoint_configs/certs/vpn-client-1003.opentest.hscic.gov.uk.jks
Appendix7 - Single Consumer Tests
| Test Name | Test Group | Short Description |
|---|---|---|
| Capability_xml_accept | Capability | Request capability statement with a fhir+xml accept http header |
| Capability_json_accept | Capability | Request capability statement with a fhir+json accept http header |
| Capability_xml_parameter | Capability | Request capability statement with a xml _format parameter |
| Capability_json_parameter | Capability | Request capability statement with a json _format parameter |
| Capability_xml_parameter_json_accept | Capability | Request capability statement with xml _format parameter and a fhir+json accept http header |
| Capability_json_parameter_xml_accept | Capability | Request capability statement with json _format parameter and a fhir+xml accept http header |
| Capability_xml_accept_gzip | Capability | Request capability statement requiring a gzipped response |
| SFFSWithValidParameters_parameter_json | Search For Free Slots | Search for free slots with a json _format parameter |
| SFFSWithValidParameters_header_json | Search For Free Slots | Search for free slots with a fhir+json http accept header |
| SFFSWithValidParameters_parameter_xml | Search For Free Slots | Search for free slots with a xml _format parameter |
| SFFSWithValidParameters_header_xml | Search For Free Slots | Search for free slots with a fhir+xml http accept header |
| SFFSWithValidParameters_JWT_NoPractitioner | Search For Free Slots | Search for free slots with a JWT that does not contain a practitioner claim element |
| SFFSWithValidParameters_3_days | Search For Free Slots | Search for free slots with a three day window from tomorrow to tomorrow+2 |
| SFFSWithValidParameters_includes | Search For Free Slots | Search for free slots with added _include parameters |
| SFFSWithValidParameters_includes_slots_only | Search For Free Slots | Search for free slots with added _include parameters response returning slots only |
| SFFSNoSlots_HappyPath | Search For Free Slots | Search for free slots returning no slots |
| SFFSInvalid | Search For Free Slots | Search for free slots using an invalid request |
| SFFSForbidden | Search For Free Slots | Search for free slots forbidden repsonse |
| SFFSWrongMethod | Search For Free Slots | Search for free slots wrong method response |
| SFFSWithBusySlots | Search For Free Slots | Search for busy slots |
| SFFSWithNoIncludes | Search For Free Slots | Search for slots with no _include parameters |
| SFFSWithNoIncludesSlotsOnly | Search For Free Slots | Search for slots with no _include parameters response returning slots only |
| SFFSWithFreeSlotsWithRevIncludes | Search For Free Slots | Search for free slots with a full set of _include and _revInclude |
| SFFSWithFreeSlotsWithGzipEncoding | Search For Free Slots | Search for free slots requiring a gzipped response |
| BookAppointment_HappyPath | Book Appointment | Happy Path Appointment booking |
| BookAppointment_NoNHSNumber | Book Appointment | Happy Path Appointment booking where no patient nhs number is supplied |
| BookAppointment_SlotAlreadyBooked | Book Appointment | Attempt to book an already booked appointment |
| BookAppointment_FailedValidation | Book Appointment | Book an apppintment with an invalid request |
| BookAppointment_Invalid | Book Appointment | Book an apppintment with an invalid request |
| BookAppointment_Forbidden | Book Appointment | Book appointment forbidden response |
| BookAppointment_ServerError | Book Appointment | Book appointment server error response |
| BookAppointment_UnsupportedMediaType | Book Appointment | Book appointment requesting an unsupported media type |
| BookAppointment_BadGateway | Book Appointment | Book appointment bad gateway response |
| BookAppointment_TelecomAndContact | Book Appointment | Book appointment with a rank 1 telecom of type phone in patient and rank2 in contact |
| BookAppointment_Contact | Book Appointment | Book appointment with a rank 1 telecom of type phone in contact |
| BookAppointment_TwoRank1 | Book Appointment | Book appointment with a rank 1 telecom of type phone in patient and rank1 in contact |
| BookAppointment_TwoRank2 | Book Appointment | Book appointment with a rank 2 telecom of type phone in patient and rank 2 in contact |
| BookAppointment_HappyPathWithGzip | Book Appointment | Book appointment with both request and response gzipped |
| BookAppointment_HappyPathWithResentRequestID | Book Appointment | Book appointment then rebook with the same request id |
| ReadNonExistentAppointment | Cancel Appointment | Read an appointment that does not exist |
| CancelAppointment_HappyPath | Cancel Appointment | Successfully cancel an appointment |
| CancelAppointment_DifferencesDetected | Cancel Appointment | Attempt to cancel an appointment supplying different appointment details |
| CancelAppointment_VersionConflict | Cancel Appointment | Attempt to cancel an appointment supplying incorrect version |
| CancelAppointment_If-MatchHeaderMissing | Cancel Appointment | Attempt to cancel an appointment without supplying an if match http header |
| CancelAppointment_ServerError | Cancel Appointment | Cancel appointment server error response |
| CancelAppointment_Forbidden | Cancel Appointment | Cancel appointment forbidden response |
| CancelAppointment_BadGateway | Cancel Appointment | Cancel appointment bad gateway response |
| CancelAppointment_GatewayTimeout | Cancel Appointment | Cancel appointment gateway timeout response |
Appendix8 - Using TKW Portal on the INT environment
Registering
Navigate to Portal - http://itw-work.itblab.nic.cfh.nhs.uk/Account/Register.aspx(HSCN access required)
Login with the following credentials -
Username = admin
Password = uecbooking
Fill out the registration form and click ‘Register’
NB: You will need to have registered your endpoint on INT and been provided with an ASID - See Path-to-Live
Testing your Consumer/Sender
Contact the Booking and Referrals Team for the configured DoS endpoint.
Testing your Provider/Receiver
Login with your newly created credentials -
You will be presented with the following options
This Portal will allow you to send tests directly to your API
Click ‘Consumer Simulator’ and you will be presented with a list of tests for different areas of functionality i.e. Search for Slots, Booking, etc. Ensure that the ‘Provider ASID’ (indicated at the top of the screen) is the one configured to direct traffic to your endpoint.
Tick the box next to the tests you wish to perform or the ‘Select All..’ for all test for an area of functionality or all tests available (top option ‘Select All Tests’)
Click ‘Run Consumer Simulator’ at the bottom of the page
When complete, the following dialog will display
The Test and Validation Report can be viewed and downloaded under the ‘Download Reports’ menu option
Viewing Reports
Consumer Reports (for reports run against a Provider/Receiver solution from the TKW Test Tool)
Provider Reports (for reports run against the TKW Provider/Receiver Test Tool from a Consumer)
Subscribing for Reports
The Portal will also email reports directly to the email address used when registering. Tick the box to subscribe to this feature.
