FIX Client Simulator User Guide

Product Overview

EPAM B2BITS FIX Client Simulator (FCS) is a rich desktop UI application. It allows to simulate multiple FIX protocol-defined buy-side- and sell-side-oriented workflows and create repeatable test scenarios for FIX sessions. FCS combines the ability to generate, manually enter, and edit FIX messages in row format and via pre-defined forms. It allows to assemble and replay FIX messages in a highly automated fashion with automatic handling of sequence numbers and identities.

FCS is used in the following use cases:

• OMS/EMS functional and stress testing
• Automated FIX integration testing 
• FIX protocol implementations
• Errors reproducing

FCS covers all spectrum of FIX protocol versions and supports custom extensions and QuickFIX-formatted dictionaries.

FIX Client Simulator features

• Establishing multiple acceptor and/or initiator sessions on local and/or remote hosts
• Support of unregistered acceptor sessions
• Restarting the working session with or without session logs restoration
• Restoring session state and configurations on FCS startup
• Support of all FIX message types (pre-trade, trade, post-trade, market data, etc.)
• Standard 4.0 - FIXLatest FIX application versions support
• Custom dictionaries support
• Overriding SenderCompID and TargetCompID for the established session
• Manual sequence numbers definition or reset
• Validation of incoming and outgoing FIX and QuickFIX messages 
• Wide range of FIX session settings including Custom Logon message
• Replaying selected log files
• Ability to load, modify, and send a file containing a preset message or batch of messages
• Enabling/disabling message re-sending
• Sending messages in a defined interval
• Tag values autoincrement
• Events monitoring:
  • sent and received messages
  • session states
• Creating, recording, editing, and running test scenarios for FIX sessions

Prerequisites and System Requirements

FIX Client Simulator is based on FIX Antenna C/C++/.NET FIX Engine. It can be installed separately or as a part of the FIX Antenna .NET package.  

1. 1. Any modern Intel-based server or workstation with a 64-bit CPU can be used as hardware.
   2. Supported operating systems:
      
      
      
      
      
      • Windows 7
      • Windows 8
      • Windows 10
      • Windows 11
      • Windows Server 2008 R2
      • Windows Server 2012
      • Windows Server 2016
      • Ubuntu Linux 20.04
      • Ubuntu Linux 22.04
      • Rocky Linux 8
   3. VS 2010 C++ Redistributable Package (x64) should be installed before the FIX Client Simulator's installation.

Installation on Linux Mint and Ubuntu

To install FIX Client Simulator on Linux Mint and Ubuntu follow the instructions below:

1. Install Wine (instruction for Ubuntu and Mint).

2. Install Winetricks using the following commands:

   sudo apt install winetricks

3. Install .NET Framework 4.8 using the following commands: 

   winetricks --force dotnet48
   winetricks --force corefonts

   If Wine prompts for installing Mono, click Cancel. Please refer to the HowTo section for more details.
   

4. Navigate to the FCS folder and run it.

   cd ./FCS_<version>
   wine Fcs.exe

Configuration

FIX Client Simulator can be configured in the Fcs.exe.config file via the following properties:

Session creation

In order to create a session, choose:  Session → Create new:

Specify the session type (Initiator or Acceptor) and parameters (SenderCompID, TargetCompID, remote host, and port) in the Create Session window:

The left column of the Create Session window includes all required parameters. If at least one of them is specified incorrectly, the session will not be created.

The right column includes extended parameters that are optional.

Custom Logon messages can be used after ticking the corresponding line at the bottom of the window.

After the session is established you will see it in the Session List section. All received messages will be displayed in the Events Viewer section below.

The "Backup Connection Parameters" section

The FIX Client Simulator 3.10.0 release introduces the "Backup Connection Parameters" section, which allows configuring a backup connection to ensure a seamless transition if the primary connection fails.

• Enable Cyclic Switch Backup Connection will cyclically try to reconnect to the primary and backup if either is lost
• Enable Auto Switch to Backup Connection automatically switches to the backup if the primary fails after a few attempts. If disabled, no backup attempt will be made
• Keep Connection State retains the same log files for both connections if enabled. If disabled, separate logs will be created for the backup connection

Multiline session display

The FIX Client Simulator 3.9.0 update allows to view sessions with multiple lines within the Session list. This view can be accessed by following these steps:

• Go to the Options menu
• Select the Multiple session information

After enabling "Multiple session information" in the Options menu, the details for each session in the list will now be displayed across multiple lines.

This provides a clearer view of all the information for each session

Manual sequence numbers definition and reset

To define sequence numbers manually, open the Create Session window and specify values in InSeqNum and OutSeqNum input fields:

To reset sequence numbers manually open the Create Session window and tick Reset Sequence number.

Display administrative messages in the console

To see or hide administrative messages in the console open the Create Session window and select the Show session messages checkbox.

You can select a session and select the Show session messages option in the Session menu or in the context menu of the session window.

This setting is stored as other session settings and restored after the session restart.

Sending messages

In order to send a message, please specify it in Send Message tab, choose a session, and press the Send button. Please note that the sequence number and sending time will be set automatically:

To override SenderCompID and TargetCompID select the Override SenderCompIDs or Override TargetCompID option in the main application menu in the Options section.

To specify the message-sending rate enter the value in the Rate input field on the Send Message tab.

Message re-sending

To enable message re-sending open Options from the context menu and select the Allow message re-sending option.

Sending selected messages

In order to send the message(s), please open the Send Message tab, choose a session, and type the message(s) in the text box. To send all messages specified in Send Message tab, press the Send all button.

To send only selected message(s) select it in the Send Message tab and press Send Selected button. Only message(s) starting with the 8 tag and ending with the 10 tag will be sent.

The sent message will be highlighted in light grey.

To send messages one by one select the message in the Send Message tab and press the Send Current and go Next button. The first sent message will be highlighted in light grey and the next message will be highlighted in dark grey.

To reset the selection of messages, please press the Reset button.

Autoincrement tag values

When sending messages, the values of the specified numeric tags can be automatically increased with each sending. Tag numbers that must be changed are set in the Autoincrement tags field. 

If you want to change the values of several tags, the tag numbers must be separated by a space, e.g. '11 38'.

If the tag is included in the Repeating group, the root tag must go first then the '\' symbol, and then the particular tag number, e.g. '453/448'.

If you want to set the value starting from which the value of the tag must be autoincremented, the tag and its value must be separated by the '=' symbol, e.g. '11 = 100' or '58 = "Hello 22"' - for value with the space or '58="Hello \" 22"' - for value with the space and " symbol.

Replay log

To send messages from the log file to the session (replay log file), please specify the log file in the Replay tab, choose a session, and press the Play button.  

Log files of the following formats may be replayed:

• *.in
• *.out
• *.fix
• *.msg
• *.body

Also provides the ability:

• to suspend sending messages from the log (Pause button)
• to stop sending messages from the log (Stop button)
• to send messages one by one (just after Loading file, after Pause, after Stop. Next button)

To send a specific range of messages it is possible to specify a filter by Sequence numbers or/and types of messages (Filter). 

The log can be replayed several times. The number of replays is set by the Send count parameter.

To specify the message-sending rate for message sending enter the value in the Rate field in the Replay tab. Also, the interval can be calculated based on the timestamp in the log file (Use the timestamps tick). 

In addition, the interval for sending messages is changed by setting a multiplier other than one (Speed parameter).

Events monitoring

The upper right part of the FIX Client Simulator window displays the message(s) to be sent.

The upper left part shows the list of active sessions.

The lower part is the Events Viewer section, where each record corresponds to one event and consists of the event time, name, and description.

Events Viewer displays events and messages of the chosen session in the Session List section. If you choose several sessions, all events belonging to the sessions are displayed in the Events Viewer section.

Whole messages or only their parts can be copied from the Events Viewer section.

• To copy the whole message with the timestamp it must be right-clicked on and then the Copy Message action must be selected in the context menu.
• To copy the message without timestamp it must be right-clicked on and then the Smart Copy action must be selected from the context menu.
• To copy the part of the message this part must be selected/highlighted and right-clicked on and then the Copy action must be selected in the context menu.

Checkboxes on the bottom of the Event Viewer section allow you to adjust the completeness of the event display, including messages. You can show or hide timestamps, header, or trailer of a FIX message, application messages, and session messages.

Events and messages in the Events Viewer section can be filtered using the Filter text field. All special symbols are supported except '/'.

Incoming, outgoing, and console messages are highlighted with different colors for visual usability. The colors can be changed in the Fcs.exe.config file.

Detailed message view from Events Viewer

In FIX Client Simulator 3.9.0, it is possible to access detailed information about individual messages within the Event Viewer. To view these details, it is required to:

• Select the required message
• Right-click on the message
• Select the option "View FIX message"

When right-clicking a message in the Event Viewer and selecting "View FIX message" a separate "Message Details" window opens. This window displays the details of the selected message in FIX message format, providing a comprehensive view of its contents.

The Events Viewer section can be spliced into three windows (Incoming, Outgoing, and Console) by choosing the Split Window checkbox. No highlighting is applied in this mode.

It is possible to auto-scroll the events by clicking Events Viewer → Auto scroll in the main menu so that Events Viewer will display the latest events first. 

To clear the Events Viewer section select the Clear event viewer option from the Events Viewer menu.

Tag order

FIX Client Simulator changes the tags' order in Event Viewer according to the dictionaries' structure. 

It happens when the dictionary used by the Simple Client, has not had the same tag order as it is in the counterparty's specification. In the Event Viewer, the messages are represented according to the dictionary's structure. The original tag order may be seen in incoming log files.

Example showing how to re-order tags for the screenshot above

 TimeInForce (tag 59) is located after block parties (tag 453)

<msgdef msgtype="D" name="New Order - Single">
...
	<block idref="Parties"/>
...  
	<field tag="59" name="TimeInForce">
		<comment>Absence of this field indicates Day order</comment>
	</field>
...
</msgdef>

TimeInForce (tag 59) is located before block parties (tag 453)

<msgdef msgtype="D" name="New Order - Single">
...            
    <field tag="59" name="TimeInForce">
        <comment>Absence of this field indicates Day order</comment>
    </field>
	<block idref="Parties"/>
... 	
</msgdef>

Searching for a raw message

Users can search for a text in a raw message using the search line below the Send Message field:

Writing messages

You can write a message in the Send Message field and edit it:

To enter a field delimiter click the right button in Send Message field and choose Insert <SOH>:

Loading predefined message or message batch

You can load a preset message and edit it before sending it.

Go to Message -> Load to load a preset message and click the Send button to send it to the counterparty. Or select Message -> Send batch to load and immediately (without editing) send a number of preset messages from one file:

Create messages from the template

You can create a template message from a dictionary with the required tags and edit it before sending it.

Go to Message -> Create to load a list of messages from a dictionary, which is corresponding to the selected session. Click the Create button to open it in the editable table for further filling of tag values and sending the message to the counterparty:

Generate messages

Execution Report

FIX Client Simulator provides the ability to autogenerate New, Partially Filled, and Filled Execution Report (35=8) for incoming New Order Single (35=D) messages in the Events Viewer section.

The following steps must be taken:

1. Select the particular incoming New Order Single (35=D) in the Events Viewer section.
2. Right-click on the selected message.
3. Select the Exec Report - New or Exec Report - Fill or Exec Report - Partial Fill action in the context menu.

Also, it is possible to autogenerate Status Execution Report (35=8) messages for incoming Order Status Request (35=H) messages in the Events Viewer section.

The following steps must be taken:

1. Select the particular incoming Order Status Request (35=H) in the Events Viewer section.
2. Right-click on the selected message.
3. Select the Exec Report - Status action in the context menu.

The Execution Report (35=8) message will be autogenerated according to the attached FIX dictionary file using the tag values present in the initial FIX message.

The autogenerated message will be added to the Send Message section.

Order Status Request

FIX Client Simulator provides the ability to autogenerate Order Status Request (35=H) for incoming New Order Single (35=D) and outgoing Execution Report (35=8) messages in the Events Viewer section.

The following steps must be taken:

1. Select the particular incoming New Order Single (35=D) or outgoing Execution Report (35=8) message in the Events Viewer section.
2. Right-click on the selected message.
3. Select the Order Status action in the context menu.

The new message will be autogenerated according to the attached FIX dictionary file using the tag values present in the initial FIX message.

The autogenerated Order Status Request (35=H) message will be added to the Send Message section.

Order Cancel Request and Order Cancel/Replace Request

FIX Client Simulator provides the ability to autogenerate Order Cancel Request (35=F), Order Cancel/Replace Request (35=G) messages for outgoing New Order Single (35=D) and incoming Execution Report (35=8) messages in the Events Viewer section.

The following steps must be taken:

1. Select the particular outgoing New Order Single (35=D) or incoming Execution Report (35=8) message in the Events Viewer section.
2. Right-click on the selected message.
3. Select the Cancel or Cancel/Replace action in the context menu.

The new message will be autogenerated according to the attached FIX dictionary file using the tag values present in the initial FIX message.

The autogenerated message will be added to the Send Message section.

Order Cancel Reject

FIX Client Simulator provides the ability to autogenerate the Order Cancel Reject (35=9) message for incoming Order Cancel Request (35=F) and Order Cancel/Replace Request (35=G) messages in the Events Viewer section.

The following steps must be taken:

1. Select the particular incoming Order Cancel Request (35=F) or Order Cancel/Replace Request (35=G) message in the Events Viewer section.
2. Right-click on the selected message.
3. Select the Order Cancel Reject action in the context menu.

The new message will be autogenerated according to the attached FIX dictionary file using the tag values present in the initial FIX message.

The autogenerated Order Cancel Reject (35=9) message will be added to the Send Message section.

Adding custom dictionaries

(Available starting from version 2.28.0 of FIX Client Simulator)

FIX Client Simulator supports multiple FIX custom dictionaries.

FIX custom dictionaries are stored in the Data folder.

The configuration of custom dictionaries is stored in the engine.properties file of the Client Simulator.

To add a custom dictionary:

1. Place a custom dictionary in the Data product folder.
   
2. Add the dictionary to the engine.properties file:

• insert the dictionary name to the list of available FIX dictionaries defined as the DictionariesFilesList
• specify the newly added dictionary to the AdditionalParsersList property in the format CustomDictionaryName@DictionaryID, CustomDictionaryName can be any name, which will appear in the list of dictionaries available, when creating a session, DictionaryID must be taken from the new dictionary: id="DictionaryID".

DictionariesFilesList = 
data/fixdic40.xml;data/fixdic41.xml;data/fixdic42.xml;data/fixdic43.xml;data/fixdic44.xml;data/fixdic50.xml;data/fixdic50sp1.xml;data/fixdic50sp2.xml;data/additional.xml
AdditionalParsersList = ADD@FIX44ADDITIONAL

3. To apply the new dictionary open the FIX version drop-down list in the Create Session dialog, the customized protocol version is shown in the drop-down list.

When you select a customized protocol version and click OK, a FIX session with specified parameters is created.

To apply a customized protocol to the incoming session, you should create an acceptor session with a defined version for it.

You can add an unlimited number of custom dictionaries to the FIX Client Simulator.

Table view

You can open a message in the table view and edit its tags, although adding and removing tags is possible only in the raw view. Right-click the Send Message field and select Edit from the context menu or press F4:

Create and run test scenarios

FIX Client Simulator provides the ability to manually create, automatically record, edit, and run test scenarios.

All existing test scenarios are displayed in the Test Scenarios tab.

The Test scenarios table consists of three columns:

• Action -  the action that can be applied to the selected test scenario. Available actions: default Run - to run the selected test scenario | Cancel - to cancel the Run action for the selected test scenario | Continue - to continue the test scenario run after the breakpoint.
• Test Scenario Name - the name of the test scenario.
• Details - the result of the test scenario run, the time taken and errors.
  
  • If the test scenario wasn't run yet, then the following text will be displayed in the Details column: 'Not Started'.
    
  • If the test scenario was run successfully, then the following text will be displayed in the Details column: 'Time taken: <mmm:sss:mcsmcsmcs>'.
    
  • If the test scenario was run unsuccessfully, then the following text will be displayed in the Details column: 'Time taken: <mmm:sss:mcsmcsmcs>. Line <number>. Errors: <error text>'.
    

Create test scenario manually

In order to manually create a test scenario the following steps must be taken:

1. Navigate to the Test Scenarios tab and press the Create Test Scenario button.
2. The Test Scenario Designer window will be opened.
   
   
   
3. In the Test Scenario Designer window, define the following fields:
   
   • Required. Test scenario name text field - the name of the new test scenario.
   • Optional. Test scenario session dropdown menu - the session for which the new test scenario will be applied. All existing sessions except unregistered acceptor sessions are available for selection in this menu. If the session is not selected, then a general test scenario will be created without session identification.
   • Optional. OnStart table field - the content and instructions for the new test scenario which will be executed on the Run action selection in the Test Scenarios tab.
   • Optional. OnMessage table field - the content and instructions for the new test scenario which will be activated on the Run action selection in the Test Scenarios tab and executed in the infinite loop to simulate FIX messages flow.
     
4. In the Test Scenario Designer window, use the following buttons to specify the context and instructions for the new test scenario:
   • Expect button - to add Expect instruction.
     
   • Expect Until button - to add Expect Until instruction.
     
   • Send button - to add Send instruction.

   • Breakpoint button - to add Breakpoint instruction.

   • Expect Then Send button - to add Expect Then Send instruction.

     Instruction	Description
     Expect	The Expect instruction specifies the next expected message in the tag=value form. If the next received message is not the same as in the Expect instruction, the test scenario run will be considered unsuccessful.  Regular expressions for values in the Expect instruction are supported.
     Expect Until	The Expect Until instruction specifies the message in the tag=value form till which FCS will be waiting to move to the next test scenario step. If the next received message is not the same as in the Expect Until instruction, FIX Client Simulator will still be waiting for the message that meets the Expect Until instruction. Regular expressions for values in the Expect Until instruction are supported.
     Send	The Send instruction defines the message to be sent in the tag=value form. The tag=value pair may be defined in the following format: <tag number>=${tag number from the Expect or Expect Until instruction message} - to define the tag with the value from the received message that met the Expect or Expect Until condition. <tag number>=$ {<first tag of repeating group>[<entry number>]<the tag in the repeating group>} - to define the tag with the value of the repeating group tag from the received message that met the Expect or Expect Until condition. <tag number>=$ {<first tag of repeating group>[<entry number>]<the tag in the repeating group>[<entry number>]<the tag in the repeating group>} - to define the tag with the value of the nesting repeating group tag from the received message that met Expect or Expect Until condition. Both pipe and SOH delimiters are supported.
     Breakpoint	The Breakpoint instruction defines the breakpoint where the test scenario execution will be paused. To continue test scenario execution the Continue button must be pressed for the selected test scenario in the Test Scenarios table in the Test Scenarios tab.
     Expect Then Send	The Expect Then Send instruction specifies the incoming message to expect and the outgoing message to reply with. The Expect Then Send instruction is configurable in the tag=value form in the Command Parameter window. Test scenario defined with the Expect Then Send instruction will be executed in the infinite loop to simulate FIX messages flow.

5. When one of the Expect, Expect Until, and Send buttons is pressed, the Command Parameter window will be opened.
   
   OR
   When the Expect then Send button is pressed another Command Parameter window will be opened.
   
   
6. Specify the context of the instructions (tag=value pairs) in the Command Parameter window.
7. Define the delay for sending messages in the Command Parameter window if needed.
8. Press the OK button when ready to save the instruction and proceed to the next test scenario step in the Test Scenario Designer window if needed.

9. Press the Save button in the Test Scenario Designer window when ready to save the created test scenario. The created test scenario will be displayed in the Test Scenarios tab and saved to the TestScenarios folder in the FCS package as <Test_scenario_name>.txt.

Record test scenario automatically

In order to automatically record a test scenario the following steps must be taken:

1. Navigate to the Send Message tab and press the Record Test Scenario button.
   
   
   
2. The New Test Scenario window will be opened.
   
   
   
3. In the New Test Scenario window, define the following fields:
   
   • Required. Test scenario name text field - the name of the new test scenario.
   • Optional. Session to capture messages dropdown menu - the session for which the messages will be captured. All existing sessions except unregistered acceptor sessions are available for selection in this menu. If the session is not selected, then a general test scenario will be created without session identification.
     
     
4. Select the Save session parameters checkbox to save the parameters of the session if needed. This checkbox is available only when the particular session is selected from the Session to capture messages dropdown menu.
   • If the Save session parameters checkbox was selected during test scenario creation, then later, if the selected session is not configured/does not exist, FCS will create it automatically to run this test scenario.
   • If the Save session parameters checkbox was selected during test scenario creation, then later, if the selected session is still configured/exists and running, FCS will just run this test scenario for this session.
   • If the Save session parameters checkbox was selected during test scenario creation, then later, if the selected session is still configured/exists but not running, FCS will try to run this test scenario for this session.
     
     
5. Select the Record an incoming message as expected checkbox to define the incoming message as an expected reply.
6. Press the OK button to start the test scenario recording.
7. Perform test scenario actions manually in the Send message tab (i.e. send and receive messages). All sent and received messages will be logged in the Events Viewer section.
8. Press the Stop Recording button to stop the test scenario recording. The recorder test scenario will be displayed in the Test Scenarios tab and saved to the TestScenarios folder in the FCS package as <Test_scenario_name>.txt. 

Edit test scenario

In order to edit the existing test scenario the following steps must be taken:

1. Navigate to the Test Scenarios tab and right-click on the particular test scenario.
2. Select the Edit option from the context menu. The Test Scenario Designer window will be opened.
3. Make changes in the context and/or instructions of the selected test scenario.
4. Press the Save button. The updated test scenario will be displayed in the Test Scenarios tab.

Rename test scenario

In order to rename the existing test scenario the following steps must be taken:

1. Navigate to the Test Scenarios tab and right-click on the particular test scenario.
2. Select the Rename option from the context menu.
3. Change the name of the test scenario.
4. The renamed test scenario will be displayed in the Test Scenarios tab.

Remove test scenario

In order to remove the existing test scenario the following steps must be taken:

1. Navigate to the Test Scenarios tab and right-click on the particular test scenario.
2. Select the Remove option from the context menu. The Do you want to remove the test scenario? warning will be displayed.
3. Press the Yes button to confirm test scenario removal.
4. The selected test scenario will be removed from the Test Scenarios tab.

Save session configuration

When creating a new session, there is an option to save session parameters and use them to restore the session after disconnecting:

There is no limit on the number of sessions that can be stored in the list, you can save as many sessions as you need or delete unnecessary sessions.

Closing session

In order to close the session correctly, please select the session and click the right mouse button selecting the Close session option:

or select Session from the context menu and choose Close or Close All:

Restore session logs

FIX Client Simulator provides the ability to restore session logs after the session restart.

In order to enable logs restoration for all sessions the following steps must be taken:

1. Configure the DaysToKeepEventViewLogs property in the Fcs.exe.config file.
   

   The DaysToKeepEventViewLogs property defines the number of days for which the session logs will be restored.

   Valid values: int

   Default value: 0

2. Select the Keep logs checkbox in the Events Viewer dropdown menu.
   

After the session restart logs for the selected number of days will be restored in the Events Viewer section.

Execution Report Reject

FIX Client Simulator provides the ability to select incoming Order Single (35=D) message and automatically form the Execution Report (35=8) with 39=8 to send in running Initiator or Acceptor session in the Events Viewer section.

The following steps must be taken:

1. Select the particular Incoming Execution Report (35=8) message in the Events Viewer section.
2. Right-click on the selected message.
3. Select the Exec Report -Reject action in the context menu.

The new message will be autogenerated according to the attached FIX dictionary file using the tag values present in the initial FIX message.

The autogenerated message will be added to the Send Message section.

Referring on repeating group without concrete index

FIX Client Simulator provides the ability to validate the tags that go into specific repeating groups not just based on a particular tag but also with an asterisk (*) instead of 0,1,2, etc. when working on test scenarios at the stages “Expect”, “Expect Until”, and “ExpectThenSend.

Managing the balance of quantities for the FIX message

When selecting “Balance quantities” checkbox the automatic population of the 32, 14, 151 tags in “Partial Fill” and “Fill” messages to maintain balance with quantities will be allowed. If Partly Fill, and Fill do not contain some of tags 32, 14, 151, the tags will be added.

In case of setting up tags with incorrect value (too big or too small), the tags will be fill in with correct values.

Setting up delay property for separate messages in ExpectThenSend command

When selecting “with random delay from” command parameter it becomes possible to manually configure the delays between messages.  The random delay interval can be set up with minimum and maximum values, and fractional values are possible for seconds.

The messages in “Then Send” Command Parameter will be sent after one another according to the selected interval.

Troubleshooting

Make sure that Microsoft Visual C++ 2010 Redistributable is installed. You can find it in the package: ./redist/vc10_vcredist_x64.exe