From 25903e6eaaa0c068b9b51bdc93e659d257be6f4d Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Wed, 3 Oct 2018 15:28:03 +0200 Subject: Update documentation This adds some instructions to build test widget using SDK and basic instruction on how to test natively on your host as well as on a target board. Change-Id: I077fda253336883bec3cd0101e61467565d679ff Signed-off-by: Romain Forlot --- docs/0_Installation.md | 30 ++++++++- docs/WriteYourTests/0_ProjectTree.md | 90 +++++++++++++++++++++++---- docs/WriteYourTests/1_BindingConfiguration.md | 4 +- docs/WriteYourTests/2_LUATestFiles.md | 4 +- 4 files changed, 109 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/0_Installation.md b/docs/0_Installation.md index e81c718..f02fa88 100644 --- a/docs/0_Installation.md +++ b/docs/0_Installation.md @@ -34,4 +34,32 @@ cd afb-test mkdir build cd build cmake .. && make -``` \ No newline at end of file +``` + +## Test natively on your host + +If you want to use the **afb-test** binding natively on your host, you have to +install it. Then *pkg-config* tool can find the **afb-test.pc** and you can +use **afm-test** launcher: + +```bash +sudo make install +# Eventually set PKG_CONFIG_PATH environment variable if not installed in the +# system directory +export PKG_CONFIG_PATH=:${PKG_CONFIG_PATH} +# The same for the PATH environment variable where afm-test has been installed +export PATH=:${PATH} +``` + +Then you can test other binding using the **afm-test** launcher. Example here, +with another binding project using **app-templates** submodule or the +**cmake-apps-module** CMake module: + +> **Note** CMake module is the new way to use **app-templates** + +```bash +cd build +cmake .. +make +afm-test package package-test +``` diff --git a/docs/WriteYourTests/0_ProjectTree.md b/docs/WriteYourTests/0_ProjectTree.md index 850487c..1905d21 100644 --- a/docs/WriteYourTests/0_ProjectTree.md +++ b/docs/WriteYourTests/0_ProjectTree.md @@ -6,7 +6,7 @@ "test" +-- etc - | +-- aft-aftest-self.json + | +-- aft-yourbinding.json | +-- CMakeLists.txt +-- fixture | +-- a-script.sh @@ -24,20 +24,19 @@ To integrate tests in your project, create a **test** subfolder at your project root directory and fulfill it with appropriate files like shown as above. -To make it quick you'll have to write your tests using lua language and store it -in the **tests** (with an "s") folder (as shown above) and change *aft-aftest-self.json* or make a new .json -file to be able to launch your tests. Note that if you make a new json file, -its name has to start with "aft-" followed by the binder's name. (e.g. -aft-low-can for the low-level-can-service) +To make it simple you'll have to write your tests using lua language and store it +in the **tests** folder (as shown above) and create a JSON configuration file +*aft-yourbinding.json* to be able to launch your tests. You'll see in the next +section how to write a proper configuration file. -*aft-aftest-self.json* is a conguration file. You'll see in the next section -how to write a proper configuration file. +> **Note** that if you create a new json file, its name has to start with "aft-" +> followed by the binder's name. (e.g. aft-low-can for the low-level-can-service) ## Integration with CMake using App-templates To make the link between your test files, config files, data files -and the test binding, -you will have to integrate them with CMake using the App-templates. +and the test binding, you will have to integrate them with CMake using the +App-templates. First you will have to create your CMake target using **PROJECT_TARGET_ADD** with your target name as parameter, it will include the target to @@ -91,9 +90,9 @@ And about test dedicated **LABELS**: > **TIP** you should use the prefix _afb-_ with your **BINDING* targets which > stand for **Application Framework Binding**. -You will find in depth explanations about it [here](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/sdk-devkit/docs/part-2/2_4-Use-app-templates.html#targets-properties). +You will find in further description about it [here](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/sdk-devkit/docs/part-2/2_4-Use-app-templates.html#targets-properties). -Here is an example of a proper CMake file: +Here is an example of a proper CMake file to include your LUA test files: ```CMake PROJECT_TARGET_ADD(test-files) @@ -105,4 +104,69 @@ PROJECT_TARGET_ADD(test-files) LABELS "TEST-DATA" OUTPUT_NAME ${TARGET_NAME} ) -``` \ No newline at end of file +``` + +## Build the test widget + +### Using CMake Apps module or app-templates + +> **Note** the CMake module is the new way to use **app-templates** + +To launch tests on a target board, you need to build a test widget. Using the +SDK, you only have to set the variable *BUILD_TEST_WGT=TRUE* when configuring +the project. + +Example from another project than **afb-test**: + +```bash +mkdir build +cd build +cmake -DBUILD_TEST_WGT=TRUE .. +make +make widget +``` + +### Without using CMake Apps module or app-templates + +Like you'd build a regular widget create a directory where you'll put your tests +materials: LUA tests, configuration and fixture files. + +Then create in that directory a **bin** directory where you'll put this +[script](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/app-templates.git;a=blob_plain;f=test-widget/launcher.sh.in;h=005c43357db3daa71b66d95d2486cd13f5cee482;hb=refs/heads/master) and name it **launcher**. To finish, you'll also need a +widget configuration file. You can use the example provided [here](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/app-templates.git;a=blob_plain;f=test-widget/test-config.xml.in;hb=refs/heads/master) and edit it +to fit your needs by replacing the variables surrounded by **@** characters. + +Example from another project than **afb-test**: + +```bash +cd build +BUILDDIR="$(pwd)" +mkdir -p package-test/bin +cd package-test +wget https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/app-templates.git;a=blob_plain;f=test-widget/launcher.sh.in;h=005c43357db3daa71b66d95d2486cd13f5cee482;hb=refs/heads/master -O bin/launcher +wget https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/app-templates.git;a=blob_plain;f=test-widget/test-config.xml.in;hb=refs/heads/master -O config.xml +vim config.xml +``` + +Then once your widget content directory is complete, use **wgtpkg-pack** utility +to create the test widget. + +```bash +cd ${BUILDDIR} +wgtpkg-pack -f -o -test.wgt package-test +``` + +## Run the test widget on the target + +Once built you can send the wgt file to your target board and launch the tests +using **afm-test** as follow: + +```bash +afm-test +``` + +**afm-test** installs the test wgt file, then runs it and uninstalls it. + +> **CAUTION**: Be cautious to not specify a regular widget's app, else it will +> be uninstalled at the end of the operation. So, if it was an important +> service/binding, others bindings or apps relying on it won't work. diff --git a/docs/WriteYourTests/1_BindingConfiguration.md b/docs/WriteYourTests/1_BindingConfiguration.md index 90b7e8d..2bd31c5 100644 --- a/docs/WriteYourTests/1_BindingConfiguration.md +++ b/docs/WriteYourTests/1_BindingConfiguration.md @@ -1,4 +1,4 @@ -# Binding configuration +# Test configuration The file `aft-test.json` contains the controller binding configuration. Here, you have to change or define the *files* key in the *args* object of the @@ -109,4 +109,4 @@ and another example which tests the low-can api: }] }] } -``` \ No newline at end of file +``` diff --git a/docs/WriteYourTests/2_LUATestFiles.md b/docs/WriteYourTests/2_LUATestFiles.md index 377b8f2..05752dd 100644 --- a/docs/WriteYourTests/2_LUATestFiles.md +++ b/docs/WriteYourTests/2_LUATestFiles.md @@ -1,7 +1,5 @@ # LUA Test files -First, ensure that you put your LUA tests files in the `lua.d` directory. - You have two differents things to take in account when you'll write your tests using this framework: *test* and *assertions*. @@ -14,4 +12,4 @@ several *assertions* which are all needed to succeed to valid the test. The framework came with several *test* and *assertion* functions to simply be able to test verb calls and events receiving. Use the simple one as often as possible and if you need more use the one that calls a callback. Specifying a -callback let you add assertions and enrich the test. \ No newline at end of file +callback let you add assertions and enrich the test. -- cgit 1.2.3-korg