File and Folder Interaction
Your SenseTalk scripts can interact with files and file system objects in a variety of ways. For instance, you can read stored data from a file on the local machine, then use that data to perform additional actions. In most cases, we recommend using the first method, described below in Accessing a File as a Container, for reading and writing to files.
SenseTalk commands and functions for working with files and file system objects operate on the local machine rather than on a system under test (SUT).
To understand how to refer to a file or folder or to access information about files and folders, see File and Folder References.
As a best practice, any files referenced within a SenseTalk script should be added to Eggplant Functional through the Resources pane in the Suite window. This method stores files to the Resources directory within the suite directory for the given suite. Although SenseTalk can access files stored elsewhere on the local file system, using the Resources directory provides additional capabilities. See the Resources Pane for more information.
Accessing a File as a Container
The simplest way to work with the contents of a file is to access the file directly as a SenseTalk container using a file
expression. Using this approach, you can read an entire file with a single command:
put file "/etc/passwd" into passwordInfo
You can write a file just as easily:
put "0,0,0,0" into file "/tmp/testing/counters"
The command above creates a file named counters
in the directory /tmp/testing
and writes the value 0,0,0,0
into it. If the /tmp/testing
directory does not exist, it is also created. If there is already a file /tmp/testing/counters
, its previous contents are completely replaced by the new value, so be careful when using this approach.
You can also access any part of the text in a file by using chunk expressions:
add 1 to item 2 of line 1 of file "/tmp/testing/counters"
This command reads the current contents of the file, adds 1 to the second item on the first line, and stores the modified value back into the file.
The following example shows how you could use a file expression to read an entire file, and then process it one line at a time:
put file "/Users/bob/Desktop/TestRead" into MyFileVar
repeat with each line output of MyFileVar
log output
end repeat
Although this example merely logs each line after it is read, you could easily add code to perform additional actions with the content of each line, which here is contained in the variable output
.
When reading a file as a container if the file does not exist or cannot be accessed, the value of the result
is set to an error message. The value of the file expression is treated as empty in this case, as shown in the following example:
put file "/nonExistent/File" into contents
put the result --> File not found: /nonExistent/File
put contents is empty --> True
If a command attempts to write to a file and fails for some reason (such as insufficient privileges for writing to the file), the result
is set to an error message.
Treating a file as a container is easy and works well for many situations. Occasionally, it might not be the most efficient approach to use if your script needs to do a significant number of read and write operations in a file. In these cases, you might prefer to use the commands described below in Commands and Functions for Working with Files.
Configuring File Behavior
When accessing a file as a container, text is interpreted during both reading and writing according to the setting of the defaultStringEncoding
global property. By default, SenseTalk uses UTF-8, a common 8-bit system for encoding Unicode characters. To read or write a file as binary data instead of as text, specify as data
:
put file "/tmp/datafile"as dataintomyData
putcontentsas dataintofile "/tmp/binaryFile"
When your SenseTalk command creates a new file, you can control the access permissions for the file as well as access to any folder created in the directory structure. See The Umask
global property for complete details about reading or setting these properties.
You can use The StrictFiles
global property to control the behavior when reading a nonexistent file as a container. The default is false, which means the nonexistent files are treated as empty. Set this property to true if you want to throw an exception if the file doesn't exist.
Commands and Functions for Working with Files
The file input and output commands (open file
, close file
, read from file
, seek in file
, and write to file
) are for creating and accessing text or binary files on your system. Use them to read and write data that is stored in the file system.
In addition to using these commands, you can access a file directly as a container within your script, as described above. Accessing a file as a container provides the simplest means of reading or manipulating its contents, but provides less control and is somewhat less efficient when performing multiple operations on the same file than the commands described here.
Open File
Command
Behavior: Opens or creates a file for reading or writing or both. The open file
command must be used to open a file before anything can be read from or written to that file with the read
or write
commands. When you are finished with a file, you should close it by using either the close file
or close all
command.
Parameters: The name of a file to open or create.
Syntax:
open file fileName { for [reading | writing | readwrite | appending | updating] }
If the fileName expression does not yield the name of an existing file, the file will be created. If fileName is not an absolute path, it is assumed to be relative to the current working folder.
Example:
open file myFile
Example:
Open file "/etc/passwd" for reading
Example:
put "/Users/bkwins/Desktop/testfolder1/testfile.txt" into MyFileVar
open file MyFileVar for appending
When you open a file, you can optionally specify the manner in which the file will be accessed. You can open files for reading only, for writing only, or for both reading and writing. The default mode is updating
if you don't specify the manner of access.
The following table lists the modes and summarizes the differences between them:
Mode | Can Read | Write / Create | Starts At | Existing File |
---|---|---|---|---|
Reading | yes | no | beginning | unchanged |
Writing | no | yes | beginning | replaces existing file |
ReadWrite | yes | yes | beginning | truncates after highest write |
Appending | yes | yes | end of file | never truncated; may grow |
Updating | yes | yes | beginning | never truncated; may grow |
All of the modes except for reading
will create the file (including the full path to it) if it doesn’t already exist.
The readwrite
, appending
, and updating
modes all open the file for both reading and writing. However, a file opened in readwrite
mode will be truncated following the last (highest) character position in the file that is written to. If nothing is written to the file, it will be left unchanged.
If you want to open a file (but only if it already exists), use file fileName exists or there is a file fileName to check for the file's existence, as shown in this example:
Example:
if there is a file myFile then
open file myFile for updating
else
answer "File " & myFile & " doesn't exist!"
exit all
end if
Related:
Close File
,Close All
: Use these commands to close open files.OpenFiles
: Use this function to get a list of all files that are currently open.
Close File
, Close All Files
Commands
Behavior: The close file
command closes an open file that was opened with the open file
command. The close all files
command closes all open files that were opened with the open file
command. Use the close file
command when your script has finished accessing a file, or use the close all files
command to close all of the currently open files.
SenseTalk automatically closes all open files whenever it stops executing your scripts, but it is a good practice for your script to close files when it is done working with them.
Parameters: For close file
, the name of a file to close is required. The close all files
command does not take a parameter.
Syntax:
close file fileName
close all { files }
The fileName should be an expression that gives the name of the file to be closed. The file name should be either the full path name of the file, or it should be given relative to the current working folder (as returned by the folder
).
Example:
close file "/etc/passwd"
Example:
close all files -- closes all open files that were opened with the open files command