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

• Allows establishing multiple acceptor/initiator sessions to local and/or remote hosts
• Supports unregistered acceptor sessions
• Supports standard FIX application versions 4.0 - FIXLatest and dialects
• Supports all FIX message types (pre-trade, trade, post-trade, market data, etc.)
• Supports a wide range of FIX session settings including Custom Logon message
• Supports custom dictionaries
• Allows creating, recording, editing, and running test scenarios for FIX sessions
• Allows overriding SenderCompID and TargetCompID for the established session
• Allows manual sequence numbers definition or reset
• Allows restarting the working session with or without session logs restoration
• Allows enabling/disabling message re-sending
• Allows events monitoring:
  • sent and received messages
  • active sessions
• Allows writing raw FIX messages, opening and editing them in the table view
• Allows monitoring FIX session state in real time
• Provides the ability to search for a text in a raw FIX message
• Provides the ability to load, modify, and send a file containing a preset message or batch of messages
• Provides the ability to send messages in a defined interval
• Provides optional ability for message validation for both incoming and outgoing messages
• Provides the ability to autoincrement tag values of FIX messages sent to the session
• Provides the ability to replay selected log files
• Provides the ability to save sessions' state and configurations to restore them on the next FCS startup

Prerequisites and System Requirements

FIX Client Simulator is based on FIX Antenna C++/.NET FIX Engine (for more details refer to FIX Antenna C/C++/.NET FIX Engine documentation). It can be installed separately or as a part of the FIX Antenna .NET package.  

1. 1. Hardware:
      Any modern Intel-based server or workstation with 64 bit CPU
   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. The list of packages that should be installed before FIX Client Simulator's installation:
      
      • VS 2010 C++ Redistributable Package (x64). It can be found in FIX Antenna or Simple Client (2.21 or higher) package\Redist directory.

Installation on Linux

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

1. Install Wine on Ubuntu or Rocky Linux.
2. Download .NET Framework 4.8.

3. Install .NET Framework 4.8 with Wine.
   

   wine ndp48-x86-x64-allos-enu.exe

   OR
   Right-click on the installer and select the Run with Wine option from the context menu.

4. Run FIX Client Simulator with Wine.

   wine Fcs.exe

   OR
   Right-click on the Fcs.exe installer and select the Run with Wine option from the context menu.

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.

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 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.

And 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 from the Events Viewer section to the clipboard this message must be right-clicked on and then the Copy Message action must be selected in the Context Menu. To copy the part of the message from the Events Viewer section to the clipboard this part of the message 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.

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

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.

You can auto-scroll the events by clicking Events Viewer → Auto scroll in the main menu, so Events Viewer will display the latest events first. 

To clear the Events Viewer section click Clear event viewer.

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

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 autogenerated message will be added to the Send Message section.

Also, FIX Client Simulator provides the ability to autogenerate New, Partially Filled, and Filled Execution Report (35=8) messages 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.

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

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

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 existing 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. Use 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. Test scenario designer table field - the content and instructions for the new test scenario.
     
     
4. In the Test Scenario Designer window, use the following buttons to specify the context and instructions for the new test scenario:
   • Add Expect button - to add Expect instruction.
     
   • Add Expect Until button - to add Expect Until instruction.
     
   • Add Send button - to add Send instruction.

   • Add Breakpoint button - to add Breakpoint 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 Expect instruction, the test scenario run will be considered as 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 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 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 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.

5. When one of the Add Expect, Add Expect Until and Add Send buttons is pressed, the Command Parameter window will be opened.
   
   
   
6. Specify the context of the instructions (tag=value pairs) in the Command Parameter window.
7. 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.

8. 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.

Troubleshooting

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