Click or drag to resize
ExcelWorksheetData Class
A class to help when dealing with spreadsheet data-driven tests.
Inheritance Hierarchy
SystemObject
  Test.FrameworkExcelWorksheetData

Namespace: Test.Framework
Assembly: Test.Framework (in Test.Framework.dll) Version: 1.0.0.0 (1.0.0.0)
Syntax
public class ExcelWorksheetData

The ExcelWorksheetData type exposes the following members.

Constructors
  NameDescription
Public methodExcelWorksheetData
Creates a new object.
Top
Properties
Methods
  NameDescription
Public methodArrayT
Returns the content of the cell at columnName cast to an array.
Public methodBool(Int32)
Returns the content of the nth cell cast to a bool.
Public methodBool(String)
Returns the content of the cell at columnName cast to a bool.
Public methodBool(Int32, Boolean)
Returns the content of the nth cell cast to a bool. If the cell is empty then 'emptyValue' is returned.
Public methodBool(String, Boolean)
Returns the content of the cell at columnName cast to a bool. If the cell is empty then 'emptyValue' is returned.
Public methodByte(Byte)
Returns the content of the nth cell cast to a byte.
Public methodByte(String)
Returns the content of the cell at columnName cast to a byte.
Public methodByte(Byte, Byte)
Returns the content of the nth cell cast to a byte. If the cell is empty then 'emptyValue' is returned.
Public methodByte(String, Byte)
Returns the content of the cell at columnName cast to a byte. If the cell is empty then 'emptyValue' is returned.
Public methodCode exampleBytes(Int32)
Returns the content of the nth cell as an array of bytes.
Public methodCode exampleBytes(String)
Returns the content of the cell at columnName as an array of bytes.
Public methodChar(Int32)
Returns the content of the nth cell cast to a char.
Public methodChar(String)
Returns the content of the cell at columnName cast to a char.
Public methodChar(Int32, Char)
Returns the content of the nth cell cast to a char. If the cell is empty then 'emptyValue' is returned.
Public methodChar(String, Char)
Returns the content of the cell at columnName cast to a char. If the cell is empty then 'emptyValue' is returned.
Public methodColumnExists
Returns true if there is a column with the name passed across.
Public methodConvertString
Converts the raw value to a value of the type passed across.
Public methodDateTime(Int32)
Returns the content of the nth cell cast to a DateTime.
Public methodDateTime(String)
Returns the content of the cell at columnName cast to a DateTime.
Public methodDateTime(Int32, DateTime)
Returns the content of the nth cell cast to a DateTime. If the cell is empty then 'emptyValue' is returned.
Public methodDateTime(String, DateTime)
Returns the content of the cell at columnName cast to a DateTime. If the cell is empty then 'emptyValue' is returned.
Public methodDecimal(Int32)
Returns the content of the nth cell cast to a decimal.
Public methodDecimal(String)
Returns the content of the cell at columnName cast to a decimal.
Public methodDecimal(Int32, Decimal)
Returns the content of the nth cell cast to a decimal. If the cell is empty then 'emptyValue' is returned.
Public methodDecimal(String, Decimal)
Returns the content of the cell at columnName cast to a decimal. If the cell is empty then 'emptyValue' is returned.
Public methodDouble(Int32)
Returns the content of the nth cell cast to a double.
Public methodDouble(String)
Returns the content of the cell at columnName cast to a double.
Public methodDouble(Int32, Double)
Returns the content of the nth cell cast to a double. If the cell is empty then 'emptyValue' is returned.
Public methodDouble(String, Double)
Returns the content of the cell at columnName cast to a double. If the cell is empty then 'emptyValue' is returned.
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Public methodEString(Int32)
Returns the content of the nth cell as a string. If the cell content is "" then String.Empty is returned. If the cell is empty then null is returned.
Public methodEString(String)
Returns the content of the cell at columnName as a string. If the cell content is "" then String.Empty is returned. If the cell is empty then null is returned.
Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodFloat(Int32)
Returns the content of the nth cell cast to a float.
Public methodFloat(String)
Returns the content of the cell at columnName cast to a float.
Public methodFloat(Int32, Single)
Returns the content of the nth cell cast to a float. If the cell is empty then 'emptyValue' is returned.
Public methodFloat(String, Single)
Returns the content of the cell at columnName cast to a float. If the cell is empty then 'emptyValue' is returned.
Public methodGetColumnT(Int32, T)
Returns the content of the column cast to type or a default value if the column has no value.
Public methodGetColumnT(String, T)
Returns the content of the column cast to type or a default value if the column has no value.
Public methodGetHashCode
Serves as a hash function for a particular type.
(Inherited from Object.)
Public methodGetNullableColumnT(Int32)
Returns the content of the column cast to a nullable of the type or null if the column has no value.
Public methodGetNullableColumnT(String)
Returns the content of the column cast to a nullable of the type or null if the column has no value.
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodInt(Int32)
Returns the content of the nth cell cast to an int.
Public methodInt(String)
Returns the content of the cell at columnName cast to an int.
Public methodInt(Int32, Int32)
Returns the content of the nth cell cast to an int. If the cell is empty then 'emptyValue' is returned.
Public methodInt(String, Int32)
Returns the content of the cell at columnName cast to an int. If the cell is empty then 'emptyValue' is returned.
Public methodLong(Int32)
Returns the content of the nth cell cast to a long.
Public methodLong(String)
Returns the content of the cell at columnName cast to a long.
Public methodLong(Int32, Int64)
Returns the content of the nth cell cast to a long. If the cell is empty then 'emptyValue' is returned.
Public methodLong(String, Int64)
Returns the content of the cell at columnName cast to a long. If the cell is empty then 'emptyValue' is returned.
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodNBool(Int32)
Returns the content of the nth cell cast to a nullable bool.
Public methodNBool(String)
Returns the content of the cell at columnName cast to a nullable bool.
Public methodNByte(Byte)
Returns the content of the nth cell cast to a nullable byte.
Public methodNByte(String)
Returns the content of the cell at columnName cast to a nullable byte.
Public methodNChar(Int32)
Returns the content of the nth cell cast to a nullable char.
Public methodNChar(String)
Returns the content of the cell at columnName cast to a nullable char.
Public methodNDateTime(Int32)
Returns the content of the nth cell cast to a nullable DateTime.
Public methodNDateTime(String)
Returns the content of the cell at columnName cast to a nullable DateTime.
Public methodNDecimal(Int32)
Returns the content of the nth cell cast to a nullable decimal.
Public methodNDecimal(String)
Returns the content of the cell at columnName cast to a nullable decimal.
Public methodNDouble(Int32)
Returns the content of the nth cell cast to a nullable double.
Public methodNDouble(String)
Returns the content of the cell at columnName cast to a nullable double.
Public methodNFloat(Int32)
Returns the content of the nth cell cast to a nullable float.
Public methodNFloat(String)
Returns the content of the cell at columnName cast to a nullable float.
Public methodNInt(Int32)
Returns the content of the nth cell cast to a nullable int.
Public methodNInt(String)
Returns the content of the cell at columnName cast to a nullable int.
Public methodNLong(Int32)
Returns the content of the nth cell cast to a nullable long.
Public methodNLong(String)
Returns the content of the cell at columnName cast to a nullable long.
Public methodNShort(Int16)
Returns the content of the nth cell cast to a nullable short.
Public methodNShort(String)
Returns the content of the cell at columnName cast to a nullable short.
Public methodParseEnumT(Int32)
Returns the content of the nth cell cast to an enum.
Public methodParseEnumT(String)
Returns the content of the cell at columnName cast to an enum.
Public methodShort(Int16)
Returns the content of the nth cell cast to an short.
Public methodShort(String)
Returns the content of the cell at columnName cast to an short.
Public methodShort(Int16, Int16)
Returns the content of the nth cell cast to an short. If the cell is empty then 'emptyValue' is returned.
Public methodShort(String, Int16)
Returns the content of the cell at columnName cast to an short. If the cell is empty then 'emptyValue' is returned.
Public methodString(Int32)
Returns the string content of the nth cell.
Public methodString(String)
Returns the string content of the cell at columnName.
Public methodString(Int32, String)
Returns the string content of the nth cell. If the cell is empty then 'emptyValue' is returned.
Public methodString(String, String)
Returns the string content of the cell at columnName. If the cell is empty then 'emptyValue' is returned.
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Public methodUInt(Int32)
Returns the content of the nth cell cast to a uint.
Public methodUInt(String)
Returns the content of the cell at columnName cast to a uint.
Public methodUInt(Int32, UInt32)
Returns the content of the nth cell cast to a uint. If the cell is empty then 'emptyValue' is returned.
Public methodUInt(String, UInt32)
Returns the content of the cell at columnName cast to a uint. If the cell is empty then 'emptyValue' is returned.
Public methodULong(Int32)
Returns the content of the nth cell cast to a ulong.
Public methodULong(String)
Returns the content of the cell at columnName cast to a ulong.
Public methodULong(Int32, UInt64)
Returns the content of the nth cell cast to a ulong. If the cell is empty then 'emptyValue' is returned.
Public methodULong(String, UInt64)
Returns the content of the cell at columnName cast to a ulong. If the cell is empty then 'emptyValue' is returned.
Public methodUShort(Int32)
Returns the content of the nth cell cast to a ushort.
Public methodUShort(String)
Returns the content of the cell at columnName cast to a ushort.
Public methodUShort(Int32, UInt16)
Returns the content of the nth cell cast to a ushort. If the cell is empty then 'emptyValue' is returned.
Public methodUShort(String, UInt16)
Returns the content of the cell at columnName cast to a ushort. If the cell is empty then 'emptyValue' is returned.
Top
Remarks

Spreadsheet data-driven tests have the advantage over database data-driven tests in that the source data is very easy to setup. You can use Excel or OpenOffice (saving the spreadsheet as a .XLS file) to create the source data in a worksheet and then tell VSTS to repeatedly run the test for each row in the sheet.

There are a few caveats when working with spreadsheets. The first is that EVERY CELL MUST BE FORMATTED FOR TEXT. If you fail to do this then the ADO.NET data adapter that is reading the spreadsheet will infer the type from the content of the first data row for the cell. If you have a column that contains the heading "Text" on row 1, the data value 42 on row 2 and the data value Hello on row 3 then you will get an exception when row 3 is read because the number on row 2 has fooled the data adapter into thinking ALL of the cells are numbers. So rule one, absolutely definitely never break it, when you start a new worksheet press Ctrl+A to select all cells and then set the format to TEXT.

Once you're past that it gets a lot easier. In your test class you need to declare the public read/write property TestContext of type TestContext. This is a magic property that is filled by VSTS at the start of the test and it will carry the data from the spreadsheet to your test.

To pull data from a worksheet in a test you add this attribute to the test method, replacing SPREADSHEET.XLS with the name of your spreadsheet and WORKSHEET$ with the name of the worksheet to read, suffixed with a dollar sign:

[DataSource("Data Source='SPREADSHEET.XLS';Provider=Microsoft.Jet.OLEDB.4.0;Persist Security Info=False;Extended Properties='Excel 8.0'", "WORKSHEET$")]

You then create an instance of ExcelWorksheetData at the start of the test and use the read methods to pull data in, usually by column name. The read methods are all named after the type that they cast the value to, read methods for nullable value types all start with a capital N. There are special methods for reading strings where you need to be able to return either null or an empty string, methods to parse the names of enum values into the correct type and methods to parse a cell's text into a byte array.

Finally you need to get the spreadsheet copied into the test deployment folder by VSTS so that the test can use it. The easiest way to do this is to create a folder on a test project that contains all of your spreadsheets (Virtual Radar Server has a folder called TestFiles under the Test.Framework project for this) and then edit the test configuration file (in VSTS either double-click LocalTestRun.testrunconfig in Solution Items or use the Test | Edit Test Settings menu entry) and add the sub-folder with the spreadsheet(s) in to the Deployment section.

Examples

This example tests the standard ASCIIEncoding object's GetString method. Assume that we have a spreadsheet called Tests.xls that contains a worksheet called TestData with the following rows and columns (all formatted as TEXT):

BytesText
40@
41A
61 62 63abc

The full code for the test class might be:

[TestClass]
public class ExampleTest
{
    public TestContext TestContext { get; set; }

    [TestMethod]
    [DataSource("Data Source='Tests.xls';Provider=Microsoft.Jet.OLEDB.4.0;Persist Security Info=False;Extended Properties='Excel 8.0'",
    "TestData$")]
    public void ASCIIEncoding_GetString_Converts_Byte_Arrays_To_Strings()
    {
        var worksheet = new ExcelWorksheetData(TestContext);

        // You could do this in one line, as below, but to make it clearer we will spell it out step-by-step:
        // Assert.AreEqual(worksheet.String("Text"), Encoding.ASCII.GetString(worksheet.ParseBytes("Bytes")));

        byte[] input = worksheet.ParseBytes("Bytes");    // Read string in cell "Bytes" and parse into a byte array
        string expected = worksheet.String("Text");      // Read content of "Text" cell as a string
        string actual = Encoding.ASCII.GetString(input);

        Assert.AreEqual(expected, actual);
    }
}

When you run the test you will get 4 executions (one per row plus one for the overall test). In this case all 4 will pass. If one failed then you would get 3/4 passed, and so on. Double-clicking on the row for the test in TestResults will show a list of results for each row. Add two to the row number to translate from the row number in TestResults to the row number in the spreadsheet (e.g. row number 0 in TestResults corresponds to row 2 in the spreadsheet).

If the intent of a test is not clear from the input and output values listed in the spreadsheet row then you may want to consider adding a 'Comments' column to the spreadsheet and describe in there what it is that you're trying to assert.

See Also