<commit_before># labs-truphone-cascades-test

Framework that provides introspective automation API for
BlackBerry 10 devices (including simulators) over a network
connection.

## Overview
This framework offers the ability to test bb10 applications
on a device or simulator.

It comes in three parts:
* static-library linked into the instrumented application
* console application on the host
* Java library for BDD/TDD

The static library provides a tcp server that the host connects
to and drives the client.

You can, if you wish, use a standard TCP connection
to communicate with the server (i.e. netcat).

Once you connect to the device/simulator it will respond
to every command as a primitive form of flow control.
If the command is successful it will respond 'OK' or
otherwise will respond with an error message.

On login you will get a single 'OK' to let you know that the
connection was made and is ready to accept commands. You can
then use 'help' or 'help <cmd>' where <cmd> is a command to
get more information.

In short you can simulate clicks on cascade controls,
enter text and test for Qt properties (such as text values
and whether a control is enabled or not).

You can also manipulate the native address book.

The provided CLI application can be used to run scripts
and it will generate an XML file with the results. The
scripts are simply the commands you would type but with
added built-in flow-control and XML output.

The Java library can be integrated into BDD/TDD environments
like easyB or JBehave

## License

BSD 3-Clause / new / simplified (see LICENSE)

## Latest Changes
#### v1.1.0
* Change the project structure to support extensions
* Add an XMPP extension (requires QXmpp - provided)

## Prerequisites
- Qt4 (sdk) & make
- BlackBerry NDK 10.1.0.1020+
- QtCreator (2.8.x+) optional: for editing only

## ToDo

- [ ] Look at integrating the new Automatic Input Control (_sys_inject_events)
* Without the above:
- [ ] Add lots of other support (hopefully AIC will mean we don't have to)

## Building
There are three projects
* test-cascades-lib - the library file to embed
* test-cascades-cli - the CLI application
* test-cascades-java - the Java API library

Or you can just use make

        1. make					# Get some info up
        2. make all-host			# Build the CLI & Java library
        3. source <bbndk-path>/bbndk-env.sh	# Pull in the BlackBerry NDK tools
        4. make all-target			# Build it for the targets
        5. sudo -E make install-cli		# Install CLI into /usr/bin (linux only)

### Building on Windows (mingw)
On windows you may need (depending if you have other make systems present) to
tell the Makefile which make binary to use, for example, I needed to do the following:

        1. mingw32-make MAKE=mingw32-make all-host	# Build on Windows
        2. c:\bbndk\bbndk-env.bat 			# (for example)
        3. make all-target				# Build it for the target

You should only need to do that for the host - once you've sourced bbdnk
then you won't need to.

### Building cont.

Other options are

        make doc			# Generate API documentation
        make clean			# Clean the build
        sudo -E make uninstall-lib	# Uninstall the library

If you want to edit & build the projects:

Both are built with QtCreator 3+ which must be configured
to use the installed BlackBerry 10 NDK for the device or simulator.

The test-cascades-cli will use the qmake/gcc/etc from the host (x86).
The test-cascades-lib will use the qmake/gcc/etc from the NDK.
The test-cascades-java will be built using Gradle.

As these are Qt projects you can use the qmake on the CLI assuming that
you have sourced the bbndk-env.sh file to setup the associated
development environment variables

## Target Library for BlackBerry

The library is a plain old static library that you need to imbed into your project and call from your main() function.

However, with recent versions, extensions are supported.

### Core

The Core is the main UI testing framework, it'll let you manipulate the UI and control it remotely.

### XMPP

This is the first extension and doesn't have to be included, it's optional. It lets you create XMPP clients so that you can automate the testing of messaging clients.

## Java Library

The java library uses gradle for dependancy management.

    gradle build	# Build the library file
    gradle test		# Run the unit tests
    gradle clean 	# Clean everything out
    gradle eclipse 	# Generate an eclipse project

## Project Integration

In your project file (.pro) add the following:

    ...
    simulator { # or device
        CONFIG(release, debug|release) {
            DESTDIR = o
        }
        CONFIG(debug, debug|release) {
            DESTDIR = o-g
            INCLUDEPATH += <path/to/lib>/test-cascades-lib
            # Simulator-Debug can be replaced with Device-Debug or Device-Release as needed
            LIBS += -ltest-cascades-lib -L<path/to/lib>/test-cascades-lib/Simulator-Debug
        }
    }
    ...


In your main C++ entry file you need to add the following:

    #include <CascadesHarness.h>
    using truphone::test::cascades::CascadesHarness;

Somewhere you need to add (before the blocking app.exec()) the following:

    // app is the Application instance
    CascadesHarness * harness = new CascadesHarness(&app);
    harness->startHarness(15000); // 15000 is the tcp port number to listen on
    
    // if you want to test XMPP stuff too
    XmppHarness * const xmppHarness = new XmppHarness();
    if (xmppHarness)
    {
        const bool xmppHarnessOk = xmppHarness->installHarness();
        Q_ASSERT(xmppHarnessOk);
        Q_UNUSED(xmppHarnessOk);
    }

A number of commands can work on objectNames so you can make the script
shorter by using them, otherwise it'll use a path to the object. Use the
record command to work out and discover how paths work.

## Running on the Device

To connect to the server running on the phone (i.e. 169.254.0.x) you need
to ensure development mode is enabled.

## Commands

The list of available commands will change as the BlackBerry 10 NDK
adds more functionality and we add more so it's best to simply
execute the help command (or read the code)

Here is a list:

* action
* click
* contacts
* dropdown
* help
* exit (close the connection)
* key
* list (select, scroll, check, tap)
* longClick
* page
* pop
* qml
* record
* segment (SegmentControl)
* sleep
* spy
* stop (recording)
* systemdialog<commit_msg>Pedantic updates to docs.<commit_after># labs-truphone-cascades-test

Framework that provides introspective automation API for
BlackBerry 10 devices (including simulators) over a network
connection.

## Overview
This framework offers the ability to test bb10 applications
on a device or simulator.

It comes in three parts:
* static-library linked into the instrumented application
* console application on the host
* Java library for BDD/TDD

The static library provides a tcp server that the host connects
to and drives the client.

You can, if you wish, use a standard TCP connection
to communicate with the server (i.e. netcat).

Once you connect to the device/simulator it will respond
to every command as a primitive form of flow control.
If the command is successful it will respond 'OK' or
otherwise will respond with an error message.

On login you will get a single 'OK' to let you know that the
connection was made and is ready to accept commands. You can
then use 'help' or 'help <cmd>' where <cmd> is a command to
get more information.

In short you can simulate clicks on cascade controls,
enter text and test for Qt properties (such as text values
and whether a control is enabled or not).

You can also manipulate the native address book.

The provided CLI application can be used to run scripts
and it will generate an XML file with the results. The
scripts are simply the commands you would type but with
added built-in flow-control and XML output.

The Java library can be integrated into BDD/TDD environments
like easyB or JBehave.

## License

BSD 3-Clause / new / simplified (see LICENSE)

## Latest Changes
#### v1.1.0
* Change the project structure to support extensions
* Add an XMPP extension (requires QXmpp - provided)

## Prerequisites
- Qt4 (sdk) & make
- BlackBerry NDK 10.1.0.1020+
- QtCreator (2.8.x+) optional: for editing only

## ToDo

- [ ] Look at integrating the new Automatic Input Control (_sys_inject_events)
* Without the above:
- [ ] Add lots of other support (hopefully AIC will mean we don't have to)

## Building
There are three projects
* test-cascades-lib - the library file to embed
* test-cascades-cli - the CLI application
* test-cascades-java - the Java API library

Or you can just use make

        1. make					# Get some info up
        2. make all-host			# Build the CLI & Java library
        3. source <bbndk-path>/bbndk-env.sh	# Pull in the BlackBerry NDK tools
        4. make all-target			# Build it for the targets
        5. sudo -E make install-cli		# Install CLI into /usr/bin (linux only)

### Building on Windows (mingw)
On windows you may need (depending if you have other make systems present) to
tell the Makefile which make binary to use, for example, I needed to do the following:

        1. mingw32-make MAKE=mingw32-make all-host	# Build on Windows
        2. c:\bbndk\bbndk-env.bat 			# (for example)
        3. make all-target				# Build it for the target

You should only need to do that for the host - once you've sourced bbdnk
then you won't need to.

### Building cont.

Other options are

        make doc			# Generate API documentation
        make clean			# Clean the build
        sudo -E make uninstall-lib	# Uninstall the library

If you want to edit & build the projects:

Both are built with QtCreator 3+ which must be configured
to use the installed BlackBerry 10 NDK for the device or simulator.

The test-cascades-cli will use the qmake/gcc/etc from the host (x86).
The test-cascades-lib will use the qmake/gcc/etc from the NDK.
The test-cascades-java will be built using Gradle.

As these are Qt projects you can use the qmake on the CLI assuming that
you have sourced the bbndk-env.sh file to setup the associated
development environment variables.

## Target Library for BlackBerry

The library is a plain old static library that you need to imbed into your project and call from your main() function.

However, with recent versions, extensions are supported.

### Core

The Core is the main UI testing framework, it'll let you manipulate the UI and control it remotely.

### XMPP

This is the first extension and doesn't have to be included, it's optional. It lets you create XMPP clients so that you can automate the testing of messaging clients.

## Java Library

The java library uses gradle for dependancy management.

    gradle build	# Build the library file
    gradle test		# Run the unit tests
    gradle clean 	# Clean everything out
    gradle eclipse 	# Generate an eclipse project

## Project Integration

In your project file (.pro) add the following:

    ...
    simulator { # or device
        CONFIG(release, debug|release) {
            DESTDIR = o
        }
        CONFIG(debug, debug|release) {
            DESTDIR = o-g
            INCLUDEPATH += <path/to/lib>/test-cascades-lib
            # Simulator-Debug can be replaced with Device-Debug or Device-Release as needed
            LIBS += -ltest-cascades-lib -L<path/to/lib>/test-cascades-lib/Simulator-Debug
        }
    }
    ...


In your main C++ entry file you need to add the following:

    #include <CascadesHarness.h>
    using truphone::test::cascades::CascadesHarness;

Somewhere you need to add (before the blocking app.exec()) the following:

    // app is the Application instance
    CascadesHarness * harness = new CascadesHarness(&app);
    harness->startHarness(15000); // 15000 is the tcp port number to listen on
    
    // if you want to test XMPP stuff too
    XmppHarness * const xmppHarness = new XmppHarness();
    if (xmppHarness)
    {
        const bool xmppHarnessOk = xmppHarness->installHarness();
        Q_ASSERT(xmppHarnessOk);
        Q_UNUSED(xmppHarnessOk);
    }

A number of commands can work on objectNames so you can make the script
shorter by using them, otherwise it'll use a path to the object. Use the
record command to work out and discover how paths work.

## Running on the Device

To connect to the server running on the phone (i.e. 169.254.0.x) you need
to ensure development mode is enabled.

## Commands

The list of available commands will change as the BlackBerry 10 NDK
adds more functionality and we add more so it's best to simply
execute the help command (or read the code).

Here is a list:

* action
* click
* contacts
* dropdown
* help
* exit (close the connection)
* key
* list (select, scroll, check, tap)
* longClick
* page
* pop
* qml
* record
* segment (SegmentControl)
* sleep
* spy
* stop (recording)
* systemdialog
{'fraction_non_alphanumeric': 0.06264051476858672, 'fraction_numerical': 0.008527792852159082, 'mean_word_length': 3.277188328912467, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4273255', 'n_tokens_mistral': 3851, 'n_tokens_neox': 3608, 'n_words': 1802}