ApperyUnit

Use it to unit-test Appery.io server-code functions.

Download: apperyunit-1.11.zip (~13M)
Source: https://github.com/a-services/apperyunit

Features

Java has to be available on the system to run ApperyUnit.

You can run it from shell scripts or just double-click apperyunit.jar file from the distribution.

ApperyUnit supports Appery.io Server-Code API in read-only mode. It means that methods of Collection object that change data in Appery DB will just print request parameters to console. More details can be found at Supported Server-Code Functions section.

Command line

Console Test

You can start the utility with au shell script.

For example, to run the example of server-code provided in distribution from command-line, one can use:

  ./au helloappery.js

To run the script in Echo mode:

  ./au helloappery.js echo

To run the script in Test mode:

  ./au helloappery.js test

More info can be found at Command-line parameters section.

GUI

To start the application in GUI mode you can double-click apperyunit.jar file or run the script without parameters:

  ./au

GUI Test

1	Server-codes in your workspace
2	Server-code libraries for the selected script
3	Query request parameters for the selected script
4	Body request parameters for the selected script
5	Output console

Usage scenarios

Data Flow

Creating new scripts

ApperyUnit can be used to create new Appery.io server-code scripts. Let’s suppose we have to implement some new functionality that can probably update the DB in some way. For example, we may need to delete some entity from the database afer some preliminary checks. Or maybe our service should change system status in some way. If we’ll create some initial version of the script and then run it in Appery, then there is a good chance that some part of the script will be executed and the other one will not due to some error. After we’ll do some fix and run our code again, we can find out that the database entity that we are using for testing was already changed by our script.

With ApperyUnit we have the convenience to save database read requests but actually do not run them. It allows us to modify and run our code till we get some acceptable results. We can also inspect JSON data received from the database. We can even edit JSON files coming from database to achieve the required level of test coverage.

The ability to run the code is particularly important for dynamic programming language like JavaScript that we are using for our server-code scripts, when missing var operator for the variable declaration or some forgotten dependency checkbox in Appery.io errors can lead to run-time errors much later, but are not diagnosed at the implementation stage.

When our server-code will be properly tested, we can copy it into Appery.io editor. With that approach database query results are saved locally. We can consider them to be the input data for our server-code. Query parameters of database update requests can be treated as the expected results of our server-code.

Refactoring the existing scripts

With ApperyUnit we can also download the existing versions of the scripts from Appery.io cloud to local folder. Inputs and outputs of database requests are saved in fixtures folder, so running the script in test mode we can ensure that script outputs are not changed and our refactorings didn’t break anything.

Echo mode

The result of each read request to Appery DB is saved in fixtures folder in files named query_1.json, query_2.json…

When echo parameter is specified, then no real requests to Appery DB will be made, but the contents of query_1.json, query_2.json… files will be used instead of HTTP requests.

Test mode

Parameters of each read request to Appery DB are saved to files named like query_r_1.json, query_r_2.json…

Similar, parameters of each write request are saved into update_r_1.json, update_r_2.json…

The result of server-code execution is saved to script_name.success.json file.

We assume that our server-code script is going to perform the same read and write requests to Appery DB after the refactoring.

It should be mentioned that write requests to Appery DB are not actually executed by ApperyUnit, so database remains unchanged after the test and we can run it once again with the same results.

When ApperyUnit is started in test mode, then read requests to Appery DB are replaced with echoes, and the contents of read and write request parameters are compared with the saved contents of query_r_#.json, update_r_#.json and script_name.success.json files.

Downloading server-codes to version control

With ApperyUnit GUI one can download server-codes from Appery.io cloud to some local folder. That folder later can be put under version control to track code changes.

Just select in left-side panel the server-code you want to download, or some folder, or even the root node of the tree and click Download button.

Documenting API with Swagger

Swagger

One can export the information about REST API from Appery.io cloud in OpenAPI format also known as Swagger. OpenAPI documentation is some JSON file that can be viewed with Swagger UI

Generating OpenAPI documentation in ApperyUnit is quite simple: just select in left-side panel the server-code or the folder and click Swagger button. You will be asked about the name of file to generate, and swagger.json file will be generated.

To use it you can:

Download the latest version of Swagger UI from GitHub,
Place your swagger.json into dist folder
In index.html replace https://petstore.swagger.io/v2/swagger.json with just swagger.json
Open index.html from some local server. There are plenty of tools around that can provide you local server for testing, maybe one of the easiest to use is Web Server for Chrome

Server-code libraries

Libraries for server-code scripts are stored in libraries folder. Dependencies between the scripts can be specified in dependencies.json file.

Example:

{
  "my_script_1": (1)
     ["my_library_2", "my_library_3"],
  "my_library_2": (2)
     ["my_library_4"]

1	Script named `my_script_1` depends on 2 libraries
2	Libraries can have their own dependencies

Command-line parameters

To try something else rather then simple helloappery script you can create some empty folder and copy 'au.sh' there. Then you should adjust the path to apperyunit.jar in this new copy of au.sh to point to the folder where you placed the distribution of ApperyUnit.

You can pass the following parameters to $AU utility in au.sh file:

script_name.js: This is the name of local file with server-code.
Required if we are not in downloading mode.
script_name.params: Parameters of server-code function can be specified in .params file as JSON
echo: Run script in echo mode - do not perform real HTTP GET requests but use query-NN.json files from fixtures folder.
test: Run script in test mode - do not perform real HTTP GET requests, compare HTTP POST requests with update-NN.json files in fixtures folder.

`.params` file

Parameters of server-code function can be specified in .params file as JSON
Request headers can be also specified in this JSON as a special headers field.
Request body can be also specified, it should be separated from JSON with a line of 4 dashes, like this: ----.

Example:

{
	"param1": "value1", (1)
	"param2": "value2",
	"param3": "value3",

	"headers": { (2)
		"X-Appery-Session-Token": [ "582345afe4b08d1f18d1479b" ]
	},

	"user": { (3)
	    "_id": "582345afe4b08d1f18d14799"
	}

}
----
{ "password":"22" } (4)

1	Parameters of server-code function
2	Request headers
3	When server-code function is secured, then it has `user` parameter in request
4	Request body string

`.paramlist` file

Each new test scenario requires its own parameters, so we need a set of .params files associated with the single server-code script. This can be specified with .paramlist file.

Each line in .paramlist is a name of .params file, or it can be empty, or commented out with # character.

Supported Server-Code Functions

ApperyUnit is intended to be used to unit-test Appery.io Server-Code functions. To be able to run tests multiple times the functions of Collection object that change data in Appery DB will just print request parameters to console but not actually change anything in DB.

Also, some Appery Server-Code APIs are not yet supported by ApperyUnit. Current status can be found at the table below.