RimWorks.Pickle.Ref 6.4.1

Pickle: RimWorld mod testing framework

<img src="https://raw.githubusercontent.com/RimWorks/Rimworld-Pickle/main/About/ModIcon.png" alt="Pickle icon" width="96" align="right">

Pickle runs automated tests for your RimWorld mod inside the game. It reads Gherkin scenarios and plays them against a live session. Your tests click the real UI, wait on real game state, and assert against the running simulation. No mocks.

Other RimWorld test frameworks, like RimTest Redux, run unit tests against your C# code. Pickle works a level up, against the live game. It catches the failures unit tests cannot see: a def that will not load, a conflicting patch, a job driver that stalls on tick 400.

Pickle is a test runner for mod authors, not a mod for players.

Install

Pickle needs RimWorld 1.6 and one patching library. Either Harmony or Concord works. Pickle prefers Concord when both are active, and logs which one it used. When a library accepts patches that never run, as Concord does after a failed startup, Pickle falls back to the other one.

1. Subscribe to Pickle on the Steam Workshop, or unzip a release into Mods/.
2. Enable Pickle and a patching library in the mod list.
3. Start a new mod from the template, or add a Pickle/ folder to an existing one.

Open the runner from the debug actions menu.

Writing steps in C#

Feature files alone need no build. To write your own step definitions, reference the RimWorks.Pickle.Ref package from a steps project:

<PackageReference Include="RimWorks.Pickle.Ref" Version="1.*"
                  ExcludeAssets="runtime" PrivateAssets="all" />

The package holds a compile-time reference assembly only. ExcludeAssets="runtime" keeps it out of your output, because the Pickle mod supplies the real RimWorks.Pickle.dll at run time. See the authoring guide.

Example

Feature: drafting
  Scenario: a drafted colonist waits for combat
    Given the save "test-colony" is loaded
    Given a colonist "Soldier" exists
    When I draft "Soldier"
    And I wait 30 ticks
    Then "Soldier" is drafted
    And "Soldier" has job "Wait_Combat"

The steps behind those lines are plain C#:

[PickleSteps]
public class DraftingSteps {
  [When("I draft {string}")]
  public void Draft(PickleContext ctx, string nickname) {
    PawnLookup.RequireLiving(nickname).drafter!.Drafted = true;
  }
}

Documentation

Contributing

npm --prefix Dashboard ci && npm --prefix Dashboard run build
dotnet build

Pickle embeds the dashboard bundles as resources, so build them first. Pickle still builds without them, and the dashboard serves a placeholder.

More modding tools from RimWorks

License

MIT