Persevere‘s latest release includes new functionality for creating clean, organized application directory structures, complete with a testing framework. Persevere now has an improved set of command-line options including a server generator, which makes it easy to build an application server directory that can be version controlled separately from the Persevere core files. The new server structure also includes a mechanism for building unit tests for Persevere.

Persevere’s new command-line script can be found in the Persevere directory at bin/persvr (or bin\persvr.bat for windows users). The first thing we will want to do is to make sure that the Persevere command-line script is available in the path. We can create a link to or add the Persevere bin directory to the environmental path.

sudo ln -s /path/to/persevere/bin/persvr /usr/bin

The first option for the Persevere command-line script we will look at is the server generator. We can create a new Persevere server instance by running:

persvr --gen-server myserver

Now we have generated a myserver server with exists in the subdirectory myserver. This subdirectory acts like a normal web directory when we run this application server. You can put HTML, JavaScript, CSS, and other files directly in the directory and they will be accessible from the web from this server. To start our new application server, we can run persvr from inside our new server directory:

cd myserver
persvr

Now let’s look at the directory structure of our new server directory. The generator creates a starting directory structure to help organize our application:

  • css – For CSS files
  • images – For images
  • index.html – The root page that is accessible from /
  • WEB-INF – This contains all the data, configuration, and server side code that should not be accessed directly as static files from the server. This directory contains these subdirectories:
    • config – This contains the Persevere configuration files which specify the data sources, schemas, and class methods for the data in Persevere
    • data – This is where the actual database files are stored
    • tests – This is where unit tests are placed

Persevere also includes two server instances in the distribution. The examples directory is a server instance with code samples. The core-tests is a server instance with Persevere’s own core unit tests.

Server Inheritance

While the newly created server instance consists of a virtually empty, clean, skeletal directory structure, Persevere provides a server inheritance mechanism so the static files and configuration information from the core Persevere directory are still available from the new server instance. This means that all the JavaScript client files and the database explorer are accessible from the server instance without any need to copy the files into the instance. The database explorer can be loaded from explorer.html in all instances, as well as the included Dojo files. Server instances also inherit the core data source, class and server-side JavaScript environmental settings from the core installation. Multiple instances can leverage a single Persevere installation for both server side configuration and library files. Therefore, the Persevere core can be updated in a single place for multiple server instances.

You can also add your own extra static files and configuration files to the core installation to be inherited by all instances. Whenever a resource file exists at the same relative path in both the server instance and the core directory, the server instance will give precedent to the instance resource. This makes it easy to override resources that would be inherited from the core. For example, one could create a blank explorer.html page to ensure that the database explorer is not accessible in a production app (although exposing the database explorer should not be a security threat, since security is enforced on the server in Persevere).

Unit Tests

Persevere provides an easy to use framework for writing unit tests for Persevere applications. To create a unit test, you can create a JavaScript file with tests in it and put it in the application’s WEB-INF/tests directory. The JavaScript file defines its unit tests with the tests method which takes an array of functions. When the unit tests are being run, each function in the array is executed, and if no exceptions are thrown, than the test passes. The test code can utilize the assert method and the assertEqual method as well. The assert method takes a single argument which when false, throws an exception. assert takes an optional second parameter that can include a message in the exception. The assertEqual method takes two arguments and throws an exception if they are not equal. For example:

// you can do test setup/initialization code here

tests([
	function testMyClass(){
		var myInstance = new MyClass();
		assert(myInstance instanceof MyClass);
		var returnVal = myInstance.inverse(33);
		assertEqual(returnVal, 1/33);
	}
]);

// any cleanup from the tests can be performed here

We can then run our test suite from the command-line:

persvr --tests

When Persevere is running the test suite, it uses a separate data directory. Rather than using the normal WEB-INF/data directory, the tests are run with WEB-INF/tests/data as the database directory. This makes it easy to run the unit tests on controlled test data. Often one of the biggest challenges of unit testing is dealing with a test database, but Persevere makes this completely automatic.

Other Command-Line Options

The Persevere command-line script includes other useful function as well, including defining the port number for the server, defining the database directory, and checking the version. To see a list of all the options, run the help command:

persvr -h

Conclusion

Persevere committer Liam Staskawicz is responsible for most of this new functionality. Persevere’s new command-line script, testing framework, and server generator provides a robust infrastructure for developing organized, deployable applications. Server instances have a clean structure that can be easily versioned and managed, complete with a built-in testing system.