swittest (core)

swittest is the brain or orchestrator of swittest. Once fed with the necessary information to perform a selected test (e.g. configuration, transaction data and expectation), its role consists in the following tasks:

Prepare and inject the configuration into switcloud.
Prepare and send the payment request data to the system under test.
Fetch the payment data once the transaction is complete.
Compare the payment data against the test expectations.
Provide a test verdict, payment data and potential error details to the calling app.
Clear the test configuration from switcloud.

Installation

To install swittest on your system you can use the dependency/package mangement tool of your choice (pip, pipx, poetry, pipenv, ...). 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.

Core (API package)

swittest can be imported and used as an API package by any Python application. Simply add the dependency to your project and import the swittest modules or sub-modules into your code.

CLI (standalone mode)

swittest can also be used as a standalone CLI tool to run EMV L2 / L3 test suites in interactive or autonomous modes.

Usage

swittest 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.
suites: To list, show or select a test suite.
tests: To list, show or run a (set of) test(s).
tags: To list and parse supported tags.
verify: To verify test suites and test files content/format.

Basics

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

# If no command is provided an error message will be displayed.swittest
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 │
│ suites Test suites commands │
│ tests Tests commands │
│ tags Tags commands │
│ verify Verify test suites and tests files │
╰──────────────────────────────────────────────────────────────────────╯

Verbose mode

By defaul the tool woks in quiet mode. If you want to see additional inputs, append the -v option to the command.

Note

The verbose mode works with the show and run commands.

Suites

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

Note

For this and all the following commands, the helper message will be automatically displayed whether or not the --help option is present, if the command requires a sub-command to be provided. For example swittest suites or swittest suites --help will produce the same result.

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 ──────────────────────────────────────────────────────────────╮
│ │
│ Current test suite'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.

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

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.

Tags

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

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

Tags commands

╭─ Options ────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────╮
│ parse Displays the meanings of the tag. There are 4 types of tag │
│ section: * Bit table: a byte is divided in 8 bits and each │
│ bit has a specific meaning * Number: the number is │
│ displayed, it can be more than 1 byte long * Byte │
│ combination: we match the value of one or multiple byte(s) │
│ to the combination lists we have in the tag data, if │
│ there is a match, we display it * Repeat: The last X │
│ sections are repeated multiple times until we reach the end │
│ of the tag │
│ list │
╰──────────────────────────────────────────────────────────────────────╯

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

swittest tags list
┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Tag ┃ Name ┃ Length ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ 95 │ Terminal Verification Results (TVR) │ 5 │
│ 82 │ Application Interchange Profile (AIP) │ 2 │
│ 9B │ Transaction Status Information (TSI) │ 2 │
│ 9F66 │ Terminal Transaction Qualifiers (TTQ) │ 4 │
│ 9F33 │ Terminal Capabilities │ 3 │
│ 9F6D │ Contactless Reader Capabilities │ 1 │
│ 9F6E │ Enhanced Contactless Reader Capabilities │ 4 │
│ 9F8204 │ Error Indication C-8 │ 6 │
│ DF8115 │ Error Indication C-2 │ 6 │
│ 9F8205 │ User Interface Request Data C-8 │ 13 │
│ DF8116 │ User Interface Request Data C-2 │ 13 │
│ 9F8210 │ Outcome Parameter Set C-8 │ 8 │
│ DF8129 │ Outcome Parameter Set C-2 │ 8 │
│ 8E │ CVM List │ 10 │
│ 9F34 │ CVM Results │ 3 │
│ 9F40 │ Additional Terminal Capabilities │ 5 │
└────────┴──────────────────────────────────────────┴────────┘

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

Info

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

swittest tags parse TVR 1234567890 Name: TVR
Full Name: Terminal Verification Results
Tag: 95
┌────┬───────────────────────────────────────────────────────────────┐
│ │ 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 │
└────┴───────────────────────────────────────────────────────────────┘

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

APIs

The API documentation is available here