testing-desktop

Instrumented tests for YubiKit Desktop

This module contains tests for execution on a physical device and with YubiKey connected via USB or tapped on an NFC reader. The test runs need a presence of someone who can tap the key when needed and therefore are these tests suitable only for local execution.

Managing YubiKeys for Testing

To protect your YubiKeys from accidental data changes during testing, you must specify which devices the test suite is allowed to use. This is done by creating a local allow list file containing the serial numbers of your designated test YubiKeys.

Instructions

1. Find the Serial Number:
   Connect your YubiKey and use the YubiKey Manager tool or the DesktopDemo app (see Listing connected devices) to find its serial number.

2. Create the Allow List File:
   Create a new file at the following specific path in the project:
   testing-desktop/src/integrationTest/resources/allowed_serials.csv

3. Add Serial Numbers:
   Open allowed_serials.csv and add the serial numbers of your test YubiKeys.
   Separate each serial number with a comma or end of line. Do not add spaces or other text.

   Example allowed_serials.csv content:

   1234567,9876543,1357911
   1212121
   2211545

The test framework will now only run on the YubiKeys specified in this file.

Device selection when multiple YubiKeys are connected

When multiple YubiKeys are plugged in, the test framework requires you to specify which device to use. Set the yubikit.testdevice property to the serial number or fingerprint of the target YubiKey.

If you run the tests without specifying a device and multiple devices are connected, the test will fail with a message listing all connected devices and their selectors.

Setting yubikit.testdevice in Android Studio / IntelliJ

1. Open Run → Edit Configurations…​

2. Select your test run configuration (or create a new one).

3. In the VM options field, add:

   -Dyubikit.testdevice=36852057

4. Click Apply → OK, then run the test.

Tip	You can also set this in the default JUnit template so it applies to all new test configurations: Edit Configurations…​ → Edit configuration templates…​ → JUnit → VM options.

Setting yubikit.testdevice in gradle.properties

Add the following line to the project root gradle.properties or to ~/.gradle/gradle.properties:

yubikit.testdevice=36852057

This is picked up automatically by the integrationTest Gradle task.

Setting yubikit.testdevice on the command line

Pass it as a system property when invoking Gradle:

./gradlew :testing-desktop:integrationTest -Dyubikit.testdevice=36852057

Running the tests

Warning

Running the instrumented tests will change PIN, PUK, management key and overwrite stored certificates in the PIV application. Make sure that the YubiKey you are using is designated for testing.

Running from Android Studio / IntelliJ

1. Connect your YubiKey(s) via USB.

2. If multiple YubiKeys are connected, configure yubikit.testdevice as described above.

3. Right-click the testing-desktop project (or a specific test class) and select Run 'All tests' (or Run '<TestName>').

Running from the command line

Single YubiKey connected:

./gradlew :testing-desktop:integrationTest

Multiple YubiKeys connected (specify serial):

./gradlew :testing-desktop:integrationTest -Dyubikit.testdevice=36852057

For running specific tests, use the --tests argument:

./gradlew :testing-desktop:integrationTest --tests 'com.yubico.yubikit.fido.ctap.Ctap2SessionInstrumentedTests$PinUvAuthV2Test.testCtap2GetInfo' -Dyubikit.testdevice=36852057

Listing connected devices

To see which YubiKeys are connected and their serial numbers / fingerprints, use the DesktopDemo app:

./gradlew :DesktopDemo:run --args="list"

Example output:

Connected YubiKeys (2):

Device #1:
  Serial:      36852057
  Fingerprint: (serial-based selector)
  Transport:   USB
  Version:     5.7.1
  Form factor: USB_A_KEYCHAIN

Device #2:
  Serial:      (not available)
  Fingerprint: DevSrvsID:4294980754
  Transport:   USB
  Version:     5.4.3
  Form factor: USB_A_KEYCHAIN