Home

Introduction

Lilac is a behavior-driven development framework for Papyrus. It has a clean, Jasmine-like syntax so you can quickly write tests for your mods.

All of Lilac is contained in a single script file, Lilac.psc. There is no complex set-up or installation.

Lilac does not require any external dependencies.

It is currently available for Fallout 4 and Skyrim.

Differences between Skyrim and Fallout 4

---

expect() and Typing

The primary difference between Lilac for Skyrim and Lilac for Fallout 4 is that the expect() function in Fallout 4 is dynamically typed.

Instead of this:

; Lilac for Skyrim
expectInt(x, to, beEqualTo, 5)
expectForm(myCoolSword, to, beEqualTo, SwordProperty)
expectFloat(y, to, beGreaterThan, 7.0)
expectBool(is_enabled, to, beTruthy)
expectString(person_name, to, beEqualTo, "Bob")

You can do this:

; Lilac for Fallout 4
expect(x, to, beEqualTo, 5)
expect(myCoolSword, to, beEqualTo, SwordProperty)
expect(y, to, beGreaterThan, 7.0)
expect(is_enabled, to, beTruthy)
expect(person_name, to, beEqualTo, "Bob")

While more convenient, you don't have to use the dynamically typed expect function if you don't want to. You can still use the statically-typed expects, like expectForm and expectInt.

Test Suite and Case Function Type

The Papyrus compiler for Fallout 4 is more strict than Skyrim when it comes to the return type of functions (and actually returning that type), and where you can use them.

To illustrate, this will compile in Skyrim's compiler:

function TestSuites()
    describe("Testing Suite", LilacTesting_TestSuite())
endFunction

function LilacTesting_TestSuite()
    it("should run a test case", LilacTesting_TestCase1())
endFunction

function LilacTesting_TestCase1()
    debug.trace(createLilacDebugMessage(INFO, "Ran test case 1"))
    expectBool(true, to, beTruthy)
endFunction

...but it will not for Fallout 4's. The reason is because the TestCases parameter (for describe()) and the TestSteps parameter (for it()) are of boolean type, but these functions all have no return type ("void").

To fix this, simply make sure that your test suite and case functions have boolean return types and return something (true or false, doesn't matter) in order to avoid compilation errors and run-time warnings:

function TestSuites()
    describe("Testing Suite", LilacTesting_TestSuite())
endFunction

; Now has Bool return type
bool function LilacTesting_TestSuite()
    it("should run a test case", LilacTesting_TestCase1())

    ; return required by compiler - has no function
    return true
endFunction

; Now has Bool return type
bool function LilacTesting_TestCase1()
    debug.trace(createLilacDebugMessage(INFO, "Ran test case 1"))
    expect(true, to, beEqualTo, true)

    ; return required by compiler - has no function
    return true
endFunction

expect() and beTruthy, beFalsy, and beNone

Using the new, generic expect() function in conjunction with the beTruthy, beFalsy, or beNone matchers (and thereby not supplying an Expected argument) can produce a harmless, but still annoying, run-time log error that looks like this:

[09/14/2016 - 08:13:40AM] warning: Passing NONE to non-object argument 4.

If this affects you, to avoid this error, simply avoid using these matchers by writing your expectations as expect(true, to, beEqualTo, true), or similar, instead.