OS Object

The OS object provides functions for basic interaction with the operating system. It includes functions for executing commands (i.e., for running programs), for getting and setting the current directory, and for getting and setting environment variables.

Array OS.argv

The OS object's read-only argv property holds the absolute filename to the current test script followed by the list of script arguments passed to squishrunner (see also squishrunner).

Here is an example that shows how to read an optional script argument:

var filename = "defaultfile.txt";
if (OS.argv.length > 1) {
    filename = OS.argv[1];
}

String OS.capture(command)

This function executes the given command in a shell (console) just like the int OS.system(command) function. The command string must hold the name of the command to be executed, and may optionally include command line arguments and shell redirection characters. What makes this function different from the int OS.system(command) function is that it captures the command's output, that is, any text that would normally go to the console (the stdout stream), and returns it as a string.

Here is an example that shows the execution of a command on Windows, and the capturing of its output:

var files = OS.capture("dir C:\\temp\\*.dat").split('\n');
for (var i in files) {
    var file = files[i];
    // ...
}

Note that in this particular case it is easier and better to use the cross-platform Array OS.listDir(path) function to get a list of files in a directory.

OS.chdir(path)

This function changes the test script's current working directory to the specified path.

Example:

var path = OS.cwd() + "/results";
OS.chdir(path);

String OS.cwd()

This function returns the current working directory as a string.

Example:

var path = OS.cwd();
test.log("Current working directory: " + path);

String OS.getenv(name)

This function returns the value of the environment variable with the given name, or an empty string if no such environment variable exists. (See also, OS.setenv(name, value).)

Example:

var homeDir = OS.getenv("HOME");
test.log("Current user's home directory: " + homeDir);

Array OS.listDir(path)

This function returns a list of all the files and directories in the directory specified by path, but excluding the special directories . (current) and .. (parent). This function does not recurse into subdirectories.

Here is an example that logs all the files that were generated in an output directory on Windows:

var files = OS.listDir("C:\\temp\\output");
for (var i in files)
    test.log("Found generated file: " + files[i]);

String OS.machine

The OS object's read-only machine property holds the name of the machine's hardware that squishrunner is running on. On Microsoft Windows systems the value is either "x86", "amd64", "arm64" or "ia64". On Unix-like systems the value is the same as the output of uname -m, e.g. "i686", "x86_64", etc.

String OS.name

The OS object's read-only name property holds the name of the operating system that squishrunner is running on. On Microsoft Windows systems the value is "Windows". On Unix-like systems the value is the same as the output of uname -s, e.g. "Linux", "Solaris", "Darwin", etc.

OS.pause(msecs)

This function pauses the script for the specified number of milliseconds. Unlike the snooze(seconds) function, the delay is fixed and not influenced by the current snooze factor setting.

Boolean OS.removeRecursively(path)

This function deletes the directory found at path including all of its contents. The function returns true on success and in case the directory did not exist in the first place. (The desired result was still achieved.)

Example:

OS.system("mkdir exampleDir");
var file = File.open("exampleDir/data", "w");
file.write("some data");
file.close();
var result = OS.removeRecursively("exampleDir");
test.log("Deletion result: " + result);

Boolean OS.rmdir(path)

This function deletes the directory found at path. It must be empty at the time of deletion. On success, the function returns true.

Example:

var oldDir = "C:\\build_old";
var result = OS.rmdir(oldDir);
test.log("Deletion result: " + result);

Boolean OS.mkpath(path)

This function creates the directory with the path path, if the path is absolute and with the path current_directory/path, if the path is relative. IMPORTANT: all necessary directories mentioned in path will be created, if they don't already exist. The function throws an error in case:

(a) call arguments are wrong; or

(b) directory already exists; or

(c) creating directory failed for any other reason like I/O error.

If successful, function returns true.

Example:

var Dir = "C:\\some_new_directory";
var result = OS.mkpath(Dir);
test.log("Directory created: " + result);

OS.setenv(name, value)

This function sets the environment variable called name to have the given value. The name environment variable is created (and then set to the given value) if it doesn't already exist. (See also, String OS.getenv(name).)

Example:

var preferredEditor = "vim";
OS.setenv("EDITOR", preferredEditor);

int OS.system(command)

This function executes the given command in a shell (console). If the execution is successful the return status is returned; otherwise -1 is returned to signify that an error occurred. The command string must hold the name of the command to be executed, and may optionally include command line arguments and shell redirection characters.

Here is an example that executes a custom application on Windows and redirects its stdout stream to a file:

var result = OS.system("C:\\testprograms\\readresult.exe > output.txt");
if (result == -1)
    test.fatal("readresult error occurred");
else if (result != 0)
   test.warning("readresult failed");

Here is another example: this sends an email on a Unix system:

var msg = "This is a mail from Squish";
OS.system("echo '" + msg + "' | mail -s Subject bugs@example.com");

See also the String OS.capture(command) function.

Array OS.version

The OS object's read-only version property holds an array with information about the operating system that squishrunner is running on. The array's elements are named "major", "minor" and "name" and denote the version number and human-readable representation.

Here is an example making use of this information to ensure test execution on supported operating systems:

var major = OS.version.major;
if (major < 7)
    test.warning("Unsupported OS version " + OS.version.name);