CLI

Installation

To install swittest-cli on your system you can use the dependency/package mangement tool of your choice (pip, pipx, poetry, pipenv, uv, ...). You simply need to configure an additional source targeting our Nexus repository beforehand.

Note

Please contact our support team to get your Nexus access details.

Usage

swittest-cli is a Typer based application that lets you call different commands organized in categories.

The following categories are available:

settings: To load, clear or show your setup settings.
log: To parse supported log files from Eval+.
tlv: To parse TLV string and name tags.
tag: To list and parse supported tags.
verify: To verify your custom test suites and test files content/format.
configs: To explore switstack's config files.
suites: To list, show or select a test suite.
tests: To list, show or run a (set of) test(s).

Basics

To run the tools, simply call swittest --help in the terminal of your choice.

# If no command is provided the help message will be displayed.swittest --help
Usage: swittest [OPTIONS] COMMAND [ARGS]...

╭─ Options ─────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current │
│ shell. │
│ --show-completion Show completion for the current shell, │
│ to copy it or customize the │
│ installation. │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────╮
│ settings Settings commands │
│ log Log parser commands │
│ tlv TLV parser commands │
│ tag Tag parser commands │
│ verify Verify test suites and tests files │
│ configs Explore switstack's config files │
│ suites Test suites commands │
│ tests Tests commands │
│ probe Paytest probe management commands │
╰───────────────────────────────────────────────────────────────────────╯

Verbose mode

Some commands have a vebose mode:

swittest suites show ...
swittest suites run ...
swittest tests show ...
swittest tests run ...

Note

The run sub-commands have three levels of verbose (-v, -vv and -vvv)

Help message

The helper message will be automatically displayed whether or not the --help option is present. For example swittest suites or swittest suites --help will produce the same result.

Settings

To use swittest CLI you have to configure some settings. Use settings sub-command to manage them.

# If no command is provided the help message will be displayed.swittest settings --help
Usage: swittest settings [OPTIONS] COMMAND [ARGS]...

Settings commands

╭─ Options ─────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────╮
│ load Load settings │
│ show Show settings │
│ clean Clean settings │
╰───────────────────────────────────────────────────────────────────────╯

Required settings to all other sub-commands that allow you to login to swittest:

swittest_url
user_email
user_password

and to run a test, you have to configure some these settings:

poi_id
org_admin_email
org_admin_password
user_machine_client_id
user_machine_client_secret

You can use a local .env file to store your settings, formated as follow:

ST_SWITTEST_URL=...
ST_USER_EMAIL=...
ST_USER_PASSWORD=...
ST_POI_ID=...
ST_ORG_ADMIN_EMAIL=...
ST_ORG_ADMIN_PASSWORD=...
ST_USER_MACHINE_CLIENT_ID=...
ST_USER_MACHINE_CLIENT_SECRET=...

You can combine .env file and settings load sub-command parameter. Sub-command parameters will override any settings defined in the .env file

Info

When no settings are explicitly loaded, Swittest falls back to automatically reading the local .env file before executing any command.

Log parser

Log file from another testing tool can be parsed by using the log command to generate a swittest test file and a vcard file. To see the list of sub-commands, type swittest log --help.

Supported tool:

Eval+ from Fime

swittest log
Usage: swittest log [OPTIONS] COMMAND [ARGS]...

Log parser commands

╭─ Options ─────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────╮
│ parse Parse a log file │
╰───────────────────────────────────────────────────────────────────────╯

Provide the input file as a parameter, and the tool will generate a corresponding test file (including its vCard) in the same directory. Optionally, you can specify a custom output location for the generated files.

swittest log parse 3B02-0101\(A_01_PPSE-withoutOptional\)_2025-01-23_21-49-02-653158.html

TLV parser

TLVs can be parsed by using the tlv command. To see the list of sub-commands, type swittest tlv --help.

swittest tlv --help
Usage: swittest tlv [OPTIONS] COMMAND [ARGS]...

TLV parser commands

╭─ Options ─────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────╮
│ parse Parse a TLV string │
╰───────────────────────────────────────────────────────────────────────╯

Each recognised tag will be named

swittest tlv parse 9F5D03000400DF810E0100DF810F0100DF8115060000000000FF
9F5D03000400DF810E0100DF810F0100DF8115060000000000FF
├── 9F5D - Application Capabilities Information (C-2), Available Offline
│ Spending Amount (AOSA) (C-3): 000400
├── DF810E - Post-Gen AC Put Data Status: 00
├── DF810F - Pre-Gen AC Put Data Status: 00
└── DF8115 - Error Indication: 0000000000FF

Tag parser

Tags can be parsed (e.g. bytes and bits explained) by using the tag command. To see the list of sub-commands, type swittest tag --help.

swittest tag --help
Usage: swittest tag [OPTIONS] COMMAND [ARGS]...

Tag parser commands

╭─ Options ─────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────╮
│ list List supported tags that can be parsed │
│ parse Parse a tag string │
╰───────────────────────────────────────────────────────────────────────╯

To list the available tags, use the list sub-command.

swittest tag list
95: TVR
82: AIP
9B: TSI
9F66: TTQ
9F33: Terminal Capabilities
9F6D: Contactless Reader Capabilities
9F6E: Enhanced Contactless Reader Capabilities
9F8204: Error Indication C-8
DF8115: Error Indication C-2
9F8205: User Interface Request Data C-8
DF8116: User Interface Request Data C-2
9F8210: Outcome Parameter Set C-8
DF8129: Outcome Parameter Set C-2
8E: CVM List
9F34: CVM Results
9F40: Additional Terminal Capabilities

To parse a tag and understand its meaning, use the parse sub-command.

swittest tag parse 95 1234567890
Tag: 95
Name: TVR
Full Name: Terminal Verification Results
┌────┬───────────────────────────────────────────────────────────────┐
│ │ 0 Offline data authentication was not performed │
│ │ 0 SDA failed │
│ │ 0 ICC data missing │
│ 12 │ 1 Card appears on terminal exception file │
│ │ 0 DDA failed │
│ │ 0 DDA failed │
│ │ 1 RFU │
│ │ 0 RFU │
└────┴───────────────────────────────────────────────────────────────┘
┌────┬───────────────────────────────────────────────────────────────┐
│ │ 0 ICC and terminal have different application versions │
│ │ 0 Expired application │
│ │ 1 Application not yet effective │
│ 34 │ 1 Requested service not allowed for card product │
│ │ 0 New card │
│ │ 1 RFU │
│ │ 0 RFU │
│ │ 0 RFU │
└────┴───────────────────────────────────────────────────────────────┘
┌────┬───────────────────────────────────────────────────────────────┐
│ │ 0 Cardholder verification was not successful │
│ │ 1 Unrecognised CVM │
│ │ 0 PIN Try Limit exceeded │
│ │ 1 PIN entry required and PIN pad not present or not working │
│ 56 │ 0 PIN entry required, PIN pad present, but PIN was not │
│ │ entered │
│ │ 1 Online PIN entered │
│ │ 1 RFU │
│ │ 0 RFU │
└────┴───────────────────────────────────────────────────────────────┘
┌────┬───────────────────────────────────────────────────────────────┐
│ │ 0 Transaction exceeds floor limit │
│ │ 1 Lower consecutive offline limit exceeded │
│ │ 1 Upper consecutive offline limit exceeded │
│ 78 │ 1 Transaction selected randomly for online processing │
│ │ 1 Merchant forced transaction online │
│ │ 0 RFU │
│ │ 0 RFU │
│ │ 0 RFU │
└────┴───────────────────────────────────────────────────────────────┘
┌────┬───────────────────────────────────────────────────────────────┐
│ │ 1 Default TDOL used │
│ │ 0 Issuer authentication failed │
│ │ 0 Script processing failed before final GENERATE AC │
│ 90 │ 1 Script processing failed after final GENERATE AC │
│ │ 0 RFU │
│ │ 0 RFU │
│ │ 0 RFU │
│ │ 0 RFU │
└────┴───────────────────────────────────────────────────────────────┘

Info

Some tags can be parsed using their tag value or their accronym, for example TVR.

Verify

The verify command can be used to check test suites and test files for errors. To see the list of sub-commands, type swittest verify --help.

swittest verify --help
Usage: swittest verify [OPTIONS] COMMAND [ARGS]...

Verify test suites and tests files

╭─ Options ────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────╮
│ all Validates all test suites in the given base directory │
│ suite Validates a specific test suite │
│ test Validates a specific test │
│ bin Validates the BIN scope file │
│ capk Validates the CAPK scope file │
│ cr Validates the CR scope file │
│ emv Validates the EMV scope file │
│ vcard Validates the vCard file │
╰──────────────────────────────────────────────────────────────────────╯

# This shows the analysis of a test suite containing 3 test files# with no error.swittest verify suite tests/assets/test_suite_without_issues.json
test_suite_without_issues
├── test_without_issues_0
│ └── Pass
├── test_without_issues_1
│ └── Pass
└── test_without_issues_2
└── Pass

# This shows the analysis of a test suite containing 8 test files# with some errors in them.swittest verify suite tests/assets/test_suite_with_issues.jsontest_suite_with_issues
├── test_without_issues_0
│ └── Pass
├── test_empty_file
│ └── Invalid JSON: EOF while parsing a value at line 1 column 0
├── test_with_bad_type
│ └── {'type': 'string_type', 'loc': ('poi_config', 'name'), 'msg':
│ 'Input should be a valid string', 'input': 10, 'url':
│ 'https://errors.pydantic.dev/2.10/v/string_type'}
├── test_with_empty_poi_config
│ ├── Missing field in test file: poi_config.name
│ └── Missing field in test file: poi_config.emv_config
├── test_without_poi_config_name
│ └── Missing field in test file: poi_config.name
├── test_without_emv_config
│ └── Missing field in test file: poi_config.emv_config
├── test_without_capk_list
│ └── Pass
└── test_without_cr_list
└── Pass

Warning

On certain OSes, launching the verify command on a large number of files can result in an error such as "Errno / OSError 24: Too many open files". This usually can be resolved by increasing the number of files that can be open at the same time at the OS level. On Linux for instance, run the command ulimit -n x to increase that number to x.

Configs

swittest configs
Usage: swittest configs [OPTIONS] COMMAND [ARGS]...

Explore switstack's config files

╭─ Options ────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────╮
│ list List config files │
│ load Load a config file │
╰──────────────────────────────────────────────────────────────────────╯

List

Explore and find some Switstack pre built config files

swittest configs list fime/l2/mastercard/mcl-v4-0-dec2024-r1-0/emvs
fime/l2/mastercard/mcl-v4-0-dec2024-r1-0/emvs
├── pps-bal-2.json
├── pps-bal.json
├── pps-cvm-1.json
...

Load

Print the file content

swittest configs load fime/l2/mastercard/mcl-v4-0-dec2024-r1-0/emvs/pps-bal-2.json
{
"emvs": {
"02_A0000000041010_00": {
"name": null,
"technology_type": "CONTACTLESS",
"kernel": "02",
"aid": "A0000000041010",
"transaction_type": "00",
"asf": true,
"tlv": "9F0100...

or create a local file

swittest configs load fime/l2/mastercard/mcl-v4-0-dec2024-r1-0/emvs/pps-bal-2.json

Suites

Test suites can be manipulated with the suites command. To see the list of sub-commands, type swittest suites --help.

swittest suites --help
Usage: swittest suites [OPTIONS] COMMAND [ARGS]...

Test suites commands

╭─ Options ────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────╮
│ list List test suites │
│ show Show test suite │
│ select Select current test suite │
│ current Show current test suite │
│ run Run a test │
╰──────────────────────────────────────────────────────────────────────╯

List

To list the available test suites, use the list sub-command.

swittest suite list
╭─ Suites ─────────────────────────────────────────────────────────────╮
│ │
│ Test suites in AWS bucket S3 swittest-testswit-bucket/assets │
│ ├── 0 - L2-Mastercard-v3.1.4-v1.0.1-dec_2021 │
│ └── 1 - L2-Mastercard-v3.1.4-v1.0.2-dec_2022 │
│ │
╰──────────────────────────────────────────────────────────────────────╯

Show

To show the description of a test suite, use the show sub-command. By default, only the environment section will be displayed. Adding -v to the command will display the complete test suite details.

swittest suites show 0 -v
╭─ Suite ──────────────────────────────────────────────────────────────╮
│ │
│ Test suite 'MCL v3.1.4 TAL2-Testing Env Dec2021' informations │
│ ├── name: MCL v3.1.4 TAL2-Testing Env Dec2021 │
│ ├── version: 0.2.0 │
│ ├── environment: │
│ │ ├── tool: eval+ │
│ │ ├── type: L2 │
│ │ ├── scheme: Mastercard │
│ │ ├── spec_version: v3.1.4 │
│ │ ├── test_plan_version: v1.0.1 │
│ │ └── test_env: Dec 2021 │
│ └── tests: │
│ ├── 3B02-0001_first-trx-5-mutualappls │
│ ├── 3B02-0002_first-trx-4-mutualappls │
│ ├── 3B02-0003_first-trx-4-mutualappls │
│ ├── 3B02-0004_first-trx-4-mutualappls │
│ ├── 3B02-0005_first-trx-4-mutualappls │
│ ├── 3B02-0006_first-trx-4-mutualappls │
│ ├── 3B02-0007_first-trx-4-mutualappls │
│ └── 3B02-0008_first-trx-4-mutualappls │
│ │
╰──────────────────────────────────────────────────────────────────────╯

Select

Finally, to select a test suite and start reunning tests, use the select sub-command with the desired test suite ID or name.

# Select a test suite by IDswittest suites select 0
L2-Mastercard-v3.1.4-v1.0.1-dec_2021 selected

# Select a test suite by nameswittest suites select L2-Mastercard-v3.1.4-v1.0.1-dec_2021
L2-Mastercard-v3.1.4-v1.0.1-dec_2021 selected

Run

Finally, to run a test or a serie of tests, use the run sub-command with the desired test ID combination. More details in tests run sub-command

Tests

Test can be manipulated with the tests command. To see the list of sub-commands, type swittest tests --help.

swittest tests --help
Usage: swittest tests [OPTIONS] COMMAND [ARGS]...

Tests commands

╭─ Options ────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────╮
│ list List tests of the current test suite │
│ show Show test of the current test suite │
│ run Run a test │
╰──────────────────────────────────────────────────────────────────────╯

List

To list the available tests, use the list sub-command.

swittest tests list
╭─ Tests ──────────────────────────────────────────────────────────────╮
│ │
│ Test suite fime_l2_mastercard_mcl-v4-0-dec2024-r1-0's tests │
│ ├── 0 - 3B02-0001_first-trx-5-mutualappls │
│ ├── 1 - 3B02-0002_first-trx-4-mutualappls │
│ ├── 2 - 3B02-0002_first-trx-4-mutualappls │
│ ├── 3 - 3B02-0002_first-trx-4-mutualappls │
│ ├── 4 - 3B02-0002_first-trx-4-mutualappls │
│ ├── 5 - 3B02-0002_first-trx-4-mutualappls │
│ ├── 6 - 3B02-0002_first-trx-4-mutualappls │
│ └── 7 - 3B02-0002_first-trx-4-mutualappls │
│ │
╰──────────────────────────────────────────────────────────────────────╯

Show

To show the description of a test, use the show sub-command. By default, only the description section will be displayed. Adding -v to the command will display extra information.

swittest tests show 0 -v
╭─ Test ───────────────────────────────────────────────────────────────╮
│ │
│ Test '3B02-0001_first-trx-5-mutualappls' informations │
│ ├── name: 3B02-0001_first-trx-5-mutualappls │
│ ├── version: 0.2.0 │
│ ├── environment: │
│ │ ├── tool: eval+ │
│ │ ├── type: L2 │
│ │ ├── scheme: Mastercard │
│ │ ├── spec_version: v3.1.4 │
│ │ ├── test_plan_version: v1.0.1 │
│ │ └── test_env: Dec 2021 │
│ ├── poi_config: │
│ │ ├── name: poi config name │
│ │ ├── capk_list: CAPK_MCL_1 │
│ │ ├── cr_list: CR_MCL_1 │
│ │ └── emv_config: PPS_MChip_1 │
│ ├── payments: │
│ │ ├── 0: │
│ │ │ ├── randoms: │
│ │ │ │ ├── AABBCCDD │
│ ... │
│ │ │ └── DF8115: 060000000000FF │
│ │ └── outcome_parameter_set: 30F0F000B8F00D00 │
│ └── vcard: Card_MCL_1 │
│ │
╰──────────────────────────────────────────────────────────────────────╯

Run

Finally, to run a test or a serie of tests, use the run sub-command with the desired test ID combination.

poetry run swittest tests run --help
Usage: swittest tests run [OPTIONS] [TEST_SELECTION]

Run a test

╭─ Arguments ───────────────────────────────────────────────────────────╮
│ test_selection [TEST_SELECTION] Specify an index, ranges │
│ and/or lists (e.g. 0-5, 8, 9, │
│ 15-40) or a single test name │
│ or 'all' │
│ [default: all] │
╰───────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────╮
│ --probe -p Wait probe connection │
│ --verbose -v INTEGER RANGE [x<=3] Verbose mode levels: │
│ Level 0 - Status and │
│ errors only │
│ Level 1 - Level 0 + │
│ payment data and log data │
│ sets │
│ Level 2 - Level 1 + parsed │
│ authorization TLV in │
│ payment data │
│ Level 3 - Level 2 + parsed │
│ DF8129, DF8115 and DF8116 │
│ tags │
│ [default: 0] │
│ --fail-only -f Display only failed │
│ results │
│ --help Show this message and │
│ exit. │
╰───────────────────────────────────────────────────────────────────────╯

Example:

swittest tests run 0-5
0 - 3B02-0001_first-trx-5-mutualappls: PASS
1 - 3B02-0002_first-trx-4-mutualappls: PASS
2 - 3B02-0003_first-trx-4-mutualappls: PASS
3 - 3B02-0004_first-trx-4-mutualappls: PASS
4 - 3B02-0005_first-trx-4-mutualappls: PASS
5 - 3B02-0006_first-trx-4-mutualappls: PASS

╭─────────────────────────────── Summary ───────────────────────────────╮
│ │
│ Test suite fime_l2_mastercard_mcl-v4-0-dec2024-r1-0 (6 PASS / 0 NON │
│ CONCLUSIVE / 0 FAIL / 0 NOT RUN) │
│ │
╰───────────────────────────────────────────────────────────────────────╯

Note

To run several individual tests, use a comma separated list. To run a contiguous serie of tests, use a dash separator. You can also combine them as follow: 1,4,5-7,8-12.

Probe

The probe command acts as an interface between swittest server and a card emulation probe. We currently support the probe designed by Paytestlab.

swittest probe --help
Usage: swittest probe [OPTIONS] COMMAND [ARGS]...

Paytest probe management commands

╭─ Options ────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────╮
│ list Broadcasts info command over network or serial ports to │
│ discover probes │
│ send Sends command to the probe using either serial or TCP │
│ communication │
│ listen Listens to the probe using either serial or TCP │
│ communication │
│ run Performs a full transaction with the card reader based on │
│ vcard data │
│ connect Connects the probe to Swittest and listens for commands │
│ from Swittest, │
│ this command is blocking and should be run in a separate │
│ terminal, │
│ it allows Swittest to control the probe for test │
│ automation, such as retrieving the POI ID or starting a │
│ payment transaction │
╰──────────────────────────────────────────────────────────────────────╯

List

The list sub-command will scan the environment for connected probes, either through WiFi or USB (virtual COM).

swittest probe list⠏ Searching probe ...
Probe(s) found at:
/dev/cu.usbserial-0001

Send & listen

The send and listen sub-commands are unitary steps that can be used to finely manipulate the probe. Most people will rather use the run one.

Run

The run sub-command performs a single virtual card transaction based on the virtual card given in argument.

swittest probe run /dev/cu.usbserial-0001 card.vcard
Starting card emulation
Setting communication protocol

Connect

The connect sub-command establishes a connection between the probe and the swittest server, then waits for test data. When a test is triggered, either via the swittest CLI or the frontend, the virtual card data is forwarded to the probe.

swittest probe connect \43102864-5d38-4926-a187-80606a14bd68 \/dev/cu.usbserial-0001 \https://swittest.swistack.ioWaiting socket server ...
Connected to https://swittest.swistack.io
Sent POI id: 43102864-5d38-4926-a187-80606a14bd68

APIs

The API documentation is available here