Xharness provides not only a way to launch an application on a simulator or a device to run the tests, but also two different ways to create applications that will contain xunit/NUnit tests to be ran.
Scaffold application
If you are only interesting in running unit test libraries on a device, that do not need any special integration with the UI or customisation and you are happy to use Xamarin, xharness provides a way to create a scaffolding application that you can later use to execute your tests.
This approach is great for those library developers that are interested in running their unit tests on a device and want to get the test results without the need of maintaining their own testing application. To do show, just follow this steps:
- Create a project that will output .dlls that contain unit tests. This tests can be base on NUnit or xunit.
- Use the provided command from xharness to create a scaffold application that will contain your dlls and that will register them with xharness
- Call xharness from your CI or console to execute the tests.
In this documentation we are making the assumption that you already have the unit test dlls.
Building the application
xharness provides the command ios package to create the scaffold application. The command takes the following options:
Packaging command that will create a iOS/tvOS/watchOS or macOS application that
can be used to run NUnit or XUnit-based test dlls
--name, -n=VALUE Name of the test application
--mtouch-extraargs, -m=VALUE
Extra arguments to be passed to mtouch.
--ignore-directory, -i=VALUE
Root directory containing all the *.ignore files
used to skip tests if needed.
--template, -t=VALUE Indicates which template to use. There are two
available ones: Managed, which uses Xamarin.[iOS|
Mac] and Native (default:Managed).
--traits-directory, --td=VALUE
Root directory that contains all the .txt files
with traits that will be skipped if needed.
--working-directory, -w=VALUE
Directory that will be used to output generated
projects
--output-directory, -o=VALUE
Directory in which the resulting package will be
outputted
--assembly, -a=VALUE An assembly to be added as part of the testing
application
--configuration=VALUE The configuration that will be used to build the
app. Default is 'Debug'
--testing-framework, --tf=VALUE
The testing framework that is used by the given
assemblies.
--platform, -p=VALUE Platform to be added as the target for the
application. Can be used multiple times to
target more platforms.
--help, -h Show this message
In order to use the tool at its full, is interesting to know what each of the following options do, others are self explanatory:
- --ignore-directory: xharness allow you to ignore certain tests depending on the application without the need to add attributes to your tests. This feature is useful when you do not have the source of the tests or control over them. The directory must contain a list of files that following the patter documented.
- --template: xharness can provide more than one template to create your applications. At the moment, the only supported template is Managed meaning that xharness will use Xamarin.iOS to create the scaffold applicaiton.
- --traits-directory: Similar option to the --ignore-directory* but in this case, the text files contains the list of traits to be ignore, that is, rather than specific tests, you can specify traits to ignore.
- --traits-directory: Used to specify if you are using NUnit or xunit as your test framework.
- --platform: The scaffold application can be created for any of the platforms supported by Xamarin.iOS, that is, iOS, watchOS or tvOS.
Taking the above information, the following is an example on how to create the application. In the example we take the following assumptions:
- We have a test dll with the name monotouch_System.Core_xunit-test.dll
- The test dlls uses xunit as the testing framework
- We are targeting a iOS simulator.
- The working directory contains the assembly we are interested in. Else, you have to provide the path to the directory that contains the testing assemblies.
Those assumptions allow us to create a scaffold application using the following command line:
dotnet xharness ios package --name="Testing App" --working-directory="." --output-directory="output-dir" --assembly="monotouch_System.Core_xunit-test.dll" --testing-framework=xUnit --platform=iPhoneSimulator
This command will output the bundle application to the path which you provided in output directory. This application can be later executed via xharness on an iPhone simulator.
Making you application more useful
More than one testing dll
The scaffold application supports more than one assembly, this can be done using more than once the --assembly options.