R. E. Cook
Contact Us 

Dr. Cook

RunningShoes Library for WinRunner 

Custom WinRunner Functions 
and Utilities,
to Your Specs

A Random Collection of WinRunner Solutions

Creating DLLs for WinRunner 
"DLLs Demystified" 
(Mercury Interactive's Worldwide Users Conference 2000)

R. E. Cook Consulting


Tutorial: Dates with RunningShoes

Continuing with our tutorial, we'll begin dealing with the date systems in RunningShoes  the date functions among the most popular functions in the library. In this first date tutorial we'll work with dates in WinRunner's native date style, as in WinRunner's get_time() and time_str statements, since these are date values that you're already familiar with.

The library functions that work with WinRunner-style dates begin with the prefix Wr. The date values that these functions take in as parameters or return are completely compatible with the date values generated by get_time(), and can be formatted with time_str. But we'll see an easy way to improve on that formatting below.

As you saw in the first tutorial, the library must be initialized before its functions are available to a WinRunner script. So begin this script with the standard initialization line:

## Load the DLL and declare the functions.
call_close "RunningShoesInit"();

Working with the current date-time

Start with something you already know, capturing the current system time in WinRunner:

## Get the current system time.
date_value = get_time();

You can always format that date using time_str(); it's readable, but that format is rarely one we can readily use for testing. If you're testing an application that uses the format "2 November 2005" while time_str() provides "Wed Nov 02 17:22:36 2005", you'll have to manipulate one or the other a fair amount to make them match. This way is much easier:

Formatting date-time values

We'll take an in-depth look at the date formatting in another tutorial, but for now here's just a quick glance to whet your appetite. 

## Format current date.
format = "D MMMM YYYY";
today = WrDateFormat(format, date_value);

The above statements create a formatted date string from the input date value, giving us "2 November 2005" as desired. Now we can test the date the application displays by comparing it directly to our formatted date string:

## Test the date
if(today == application_date)
    date_test = PASS;
    date_test = FAIL;

WrDateFormat() takes the input date_value and formats it according to the specified format rule. Another tutorial deals with the date formatting in much greater detail. For now, the format string says we want a date that contains the one- or two-digit day ("D"), followed by the name of the month ("MMMM"), followed by the four-digit year ("YYYY"). If instead you want a 2-digit day, the month name abbreviated, and a 2-digit year, the format string would be:

## Format current date.
format = "DD MMM YY";
today = WrDateFormat(format, date_value);

As you can see, formatting dates is extremely simple with the WrDateFormat() function.

Date calculations

We'll walk through a few examples of calculating various days, starting with some simple ones. Let's first determine how many days remain until the end of the year.

## Get the current system time.
date_value = get_time();

## Determine remaining days in the year.
days_remain = WrDaysRemainingInYear(date_value)

On 2 Nov 05, that code says 59 days remain in the year. If you need the days remaining in the month rather than in the year, it's just one extra step:

## Determine remaining days in the month.
last_day = WrEndOfMonth(date_value);
days_remain = WrDaysInPeriod(date_value, last_day);

WrEndOfMonth() gives us the date value of the last day of the month containing the input date value (30, for November); WrDaysInPeriod() calculates the number of days in the period defined by the two input date values. Executing that code on 2 Nov gives 29 days remaining (including today, which isn't over yet).

If we need the day of the month rather than the date value, we can directly convert the end-of-month date value into the day with the function WrDay(). We'll see below we could also use WrDaysInMonth().

## Determine last day of the month.
date_value = WrEndOfMonth(date_value);
last_day = WrDay(date_value);

Why are we dealing with the end of the month? Let's say you're testing a banking application that credits an interest payment to customers' savings accounts at the end of each quarter (31 Mar, 30 Jun, 30 Sept, 31 Dec). You run the test on various days; only those tests run on the last day of the last month of the quarter have an interest payment as the expected result. Thus your test script must determine whether the current date is the last day of the quarter. 

## Determine whether today is end of quarter.
## Get needed date information.
now = get_time();
month = WrMonth(now); # 1 - 12
today = WrDay(now); # 1 - 31
last_day = WrDaysInMonth(now); # 28 - 31

## Is it the end of quarter?
if(month % 3 == 0 && today == last_day)
    end_of_quarter = TRUE;
    end_of_quarter = FALSE;

The above code determines the current month and day, and the last day of the current month. From that information it is easy to determine whether today is the end of the quarter, by determining both whether today is the end of the month and the month is the last month of the quarter (month % 3 yields 0 when the month is evenly divisible by 3).

Date-time values other than now

WinRunner makes it easy to get the date value for the current date-time. But what about when you need to work with other dates? Without the date functions in RunningShoes, it's still possible to work with dates relative to today (e.g., 3 weeks from today) by manipulating the value from get_time(). Also, the date (Y2K) functions allow some limited date handling on date fields in your application, although those date functions require multistage set up and handle a limited set of allowable date formats. But for anything beyond simple calculations you'll have to code a lot of TSL.

To top it off, WinRunner provides no means at all for determining the date value of some arbitrary date and time, while RunningShoes makes that simple.

As you saw above, RunningShoes provides functions for easily determining the date value of specific days, such as the end of the month. Some others are the first day of the month, yesterday, tomorrow, and a few other obvious days. Other days that do not have their own function can still be determined easily with an extra step or two. RunningShoes also allows converting any given date to a WinRunner date value, as you'll see below.

Days relative to now

With WinRunner dates, it's always easy to add or subtract a certain number of days, given that a day is 86,400 seconds.

Hint: While going through these examples, put the expression time_str(target) in the watch list and step through the code, just to ensure you've gotten the correct dates.

## Find the date value for one week from today.
now = get_time();
target = now + (7 * 86400);

You can also do that with a RunningShoes function. This one really isn't easier, but it does make the code more clear:

## Find the date value for one week from today.
now = get_time();
target = WrAddDays(now, 7);

But what about 2 months from today, since months have different lengths? You could determine the number of days in each month between now and then. You'll also have to correct for ending up in a shorter month, such as adding 2 months from 31 December. That calculation would normally result in 28 February (or 29 Feb in a leap year, of course). That's a lot of code to write and maintain. Here's an easier way:

## Find the date value for 2 months from today.
now = get_time();
target = WrAddMonths(now, 2);

If now is 3 Nov, target is 3 Dec. But if now is 31 Dec 05, target is 28 Feb 06, since 31 Feb clearly doesn't exist. Similar considerations apply when adding years to 29 Feb, which doesn't exist in most years.

## Find this day last year.
now = get_time();
target = WrAddYears(now, -1);

The above code snippet shows that you can go backwards in time by adding a negative number of days, months or years.

We can perform a wide variety of calendar calculations, as long as we have a date-time value to work with. As long as we're basing our calculations on today, we can work with the date value from WinRunner's get_time() statement and use RunningShoes functions to calculate from that date. Next we'll look at dealing with other days, when get_time() doesn't provide any help.

Absolute dates

What about 26 August 1996? RunningShoes makes it simple to determine the date value for a specific date. This is one step where the library's power becomes really obvious:

## Find the date value for a specific date.
year = 1996;
month = 8;
day = 26;
date_value = WrFromDate(year, month, day);

The above code gives us a date value of 841035600, which time_str tells us is "Mon Aug 26 00:00:00 1996". 

When you're working with variables that allow the date components to be set dynamically, you might need to test the result to ensure those components are valid:

## Test for valid date.
date_value = WrFromDate(year, month, day);
if(date_value == E_OUT_OF_RANGE)
    pause("invalid date inputs");

Most of the date functions return an error code (negative) if the inputs are invalid. Check the online documentation for the specific functions you're working with to see what values each function returns.

Notice that WrFromDate() uses only the components of the date, without any mention of time of day. Therefore the result is the beginning of the day (the time is 0, or midnight). If you need the time of day also, call the function WrFromDateTime() to include the time:

## Find the date value for a specific date and time.
year = 1996;
month = 8;
day = 26;
hour = 13;
minute = 49;
second = 11;
date = WrFromDateTime(year, month, day, hour, minute, second);

The result of the above code is date = 841085351, equivalent to "Mon Aug 26 13:49:11 1996". The more complicated parameter list of WrFromDateTime() suggests using the simpler WrFromDate() if the time of day isn't needed. You'll see a complete set of functions for time calculations in another tutorial, so we won't go into more detail here.

Now that you've determined the date value for the given date, you can use that date value in any of the Wr- date functions, such as those you worked with above. You'll see in the next section that you can work with the individual date parts in RunningShoes, but if you don't need the individual parts it's easier to track a single date value than multiple components of a date.

You're through with the library for now, so call the script that unloads the DLL:

call_close "RunningShoesEnd"();

Created 2 November 2005 

Top of  This Page | R. E. Cook Home Page

Copyright R. E. Cook Consulting, 2000 - 2011.
All rights reserved.

The site is designed to look best when viewed with Internet Explorer 5.0 - 8.0. Results with other browsers will probably deviate from what is intended.

NOTE: This website refers to registered trademarks and service marks that are owned by other companies, including Mercury Interactive, WinRunner, TestDirector, TSL, Microsoft, Windows.