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 │
╰───────────────────────────────────────────────────────────────────────╯

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 │
│ suite │
│ test │
╰──────────────────────────────────────────────────────────────────────╯

all performs a check on a complete directory (containing test suites at its root).
suite performs a check on a targeted test suite.
test performs a check on a targeted test 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.

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 ───────────────────────────────────────────────────────────╮
│ current Show current test suite │
│ list List test suites │
│ run Run all tests or a selection of tests │
│ select Select current test suite │
│ show Show test suite │
╰──────────────────────────────────────────────────────────────────────╯

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 │
│ │
╰──────────────────────────────────────────────────────────────────────╯

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 │
│ │
╰──────────────────────────────────────────────────────────────────────╯

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

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 │
│ run Run all tests or a selection of tests │
│ show Show test of the current test suite │
╰──────────────────────────────────────────────────────────────────────╯

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 │
│ │
╰──────────────────────────────────────────────────────────────────────╯

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 │
│ │
╰──────────────────────────────────────────────────────────────────────╯

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.

APIs

The API documentation is available here