Shallow wrapper

CONTRIBUTING.md

@@ -81,6 +81,24 @@ When submitting a new feature, add tests for all functionality.
 
 We use [LuaCov](https://keplerproject.github.io/luacov) for keeping track of code coverage. We'd like it to be as close to 100% as possible, but it's not always possible. Adding tests just for the purpose of getting coverage isn't useful; we should strive to make only useful tests!
 
+### Snapshots
+As part of the test suite, there are tests that generates snapshot files (located under `./RoactSnapshots`). To sync back the generated StringValues produce by these on the file system, we suggest using a tool like [`run-in-roblox`](https://github.com/LPGhatguy/run-in-roblox) to make the workflow as simple as possible. In the case where you only need to sync a few files, you can use the plugin to automatically copy back the generated string values from the run mode into module scripts when going back to edit mode. Then simply copy-paste into the new snapshots into the file-system.
+
+#### Using run-in-roblox
+You can install run-in-roblox using [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) with the following command.
+```
+cargo install run-in-roblox
+```
+Once installed, run the [syncing script](bin/sync_snapshots.lua) to execute the tests and sync the created ModuleScripts from Roblox Studio to the file system. This script works by doing 3 tasks:
+1. Build a test place with rojo
+2. Use run-in-roblox to run [run-tests-snapshots.lua](bin/run-tests-snapshots.lua) in the place file
+3. Parse the output of run-in-roblox to copy back the new snapshots to the file system
+
+Run this script using lua stand alone interpreter
+```
+lua bin/run-tests-snapshots.lua
+```
+
 ## Release Checklist
 When releasing a new version of Roact, do these things:
 

RoactSnapshots/component-with-event-props.lua

@@ -0,0 +1,19 @@
+return function(dependencies)
+  local Roact = dependencies.Roact
+  local ElementKind = dependencies.ElementKind
+  local Markers = dependencies.Markers
+
+  return {
+    type = {
+      kind = ElementKind.Host,
+      className = "TextButton",
+    },
+    props = {
+      [Roact.Event.Activated] = Markers.AnonymousFunction,
+      [Roact.Event.MouseButton1Click] = Markers.AnonymousFunction,
+      [Roact.Change.AbsoluteSize] = Markers.AnonymousFunction,
+      [Roact.Change.Visible] = Markers.AnonymousFunction,
+    },
+    children = {},
+  }
+end

RoactSnapshots/function-component-children.lua

@@ -0,0 +1,35 @@
+return function(dependencies)
+  local Roact = dependencies.Roact
+  local ElementKind = dependencies.ElementKind
+  local Markers = dependencies.Markers
+
+  return {
+    type = {
+      kind = ElementKind.Host,
+      className = "Frame",
+    },
+    props = {},
+    children = {
+      {
+        type = {
+          kind = ElementKind.Function,
+        },
+        hostKey = "LabelA",
+        props = {
+          Text = "I am label A",
+        },
+        children = {},
+      },
+      {
+        type = {
+          kind = ElementKind.Function,
+        },
+        hostKey = "LabelB",
+        props = {
+          Text = "I am label B",
+        },
+        children = {},
+      },
+    },
+  }
+end

RoactSnapshots/host-frame-with-multiple-props.lua

@@ -0,0 +1,23 @@
+return function(dependencies)
+  local Roact = dependencies.Roact
+  local ElementKind = dependencies.ElementKind
+  local Markers = dependencies.Markers
+
+  return {
+    type = {
+      kind = ElementKind.Host,
+      className = "Frame",
+    },
+    props = {
+      AnchorPoint = Vector2.new(0, 0.5),
+      BackgroundColor3 = Color3.new(0.1, 0.2, 0.3),
+      BackgroundTransparency = 0.205,
+      ClipsDescendants = false,
+      Size = UDim2.new(0.5, 0, 0.4, 1),
+      SizeConstraint = Enum.SizeConstraint.RelativeXY,
+      Visible = true,
+      ZIndex = 5,
+    },
+    children = {},
+  }
+end

RoactSnapshots/stateful-component-children.lua

@@ -0,0 +1,28 @@
+return function(dependencies)
+  local Roact = dependencies.Roact
+  local ElementKind = dependencies.ElementKind
+  local Markers = dependencies.Markers
+
+  return {
+    type = {
+      kind = ElementKind.Host,
+      className = "Frame",
+    },
+    props = {},
+    children = {
+      {
+        type = {
+          kind = ElementKind.Stateful,
+          componentName = "CoolComponent",
+        },
+        hostKey = "Child",
+        props = {
+          label = {
+            Text = "foo",
+          },
+        },
+        children = {},
+      },
+    },
+  }
+end

SnapshotsPlugin/EditModeMain.lua

@@ -0,0 +1,41 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Settings = require(script.Parent.Settings)
+
+local function SyncSnapshots(newSnapshots)
+	local snapshotsFolder = ReplicatedStorage:FindFirstChild(Settings.SnapshotFolderName)
+
+	if not snapshotsFolder then
+		snapshotsFolder = Instance.new("Folder")
+		snapshotsFolder.Name = Settings.SnapshotFolderName
+		snapshotsFolder.Parent = ReplicatedStorage
+	end
+
+	for name, value in pairs(newSnapshots) do
+		local snapshot = Instance.new("ModuleScript")
+		snapshot.Name = name
+		snapshot.Source = value
+		snapshot.Parent = snapshotsFolder
+	end
+end
+
+local function PluginEditMode(plugin)
+	local isPluginDeactivated = false
+
+	plugin.Deactivation:Connect(function()
+		isPluginDeactivated = true
+	end)
+
+	while not isPluginDeactivated do
+		local newSnapshots = plugin:GetSetting(Settings.PluginSettingName)
+
+		if newSnapshots then
+			SyncSnapshots(newSnapshots)
+			plugin:SetSetting(Settings.PluginSettingName, false)
+		end
+
+		wait(Settings.SyncDelay)
+	end
+end
+
+return PluginEditMode

SnapshotsPlugin/RunModeMain.lua

@@ -0,0 +1,25 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Settings = require(script.Parent.Settings)
+
+local function PluginRunMode(plugin)
+	plugin.Unloading:Connect(function()
+		local snapshotsFolder = ReplicatedStorage:FindFirstChild(Settings.SnapshotFolderName)
+
+		local newSnapshots = {}
+
+		if not snapshotsFolder then
+			return
+		end
+
+		for _, snapshot in pairs(snapshotsFolder:GetChildren()) do
+			if snapshot:IsA("StringValue") then
+				newSnapshots[snapshot.Name] = snapshot.Value
+			end
+		end
+
+		plugin:SetSetting(Settings.PluginSettingName, newSnapshots)
+	end)
+end
+
+return PluginRunMode

SnapshotsPlugin/Settings.lua

@@ -0,0 +1,17 @@
+local function IndexError(_, key)
+	local message = ("%q (%s) is not a valid member of Settings"):format(
+		tostring(key),
+		typeof(key)
+	)
+
+	error(message, 2)
+end
+
+return setmetatable({
+	SnapshotFolderName = "RoactSnapshots",
+	PluginSettingName = "NewRoactSnapshots",
+	SyncDelay = 1,
+}, {
+	__index = IndexError,
+	__newindex = IndexError,
+})

SnapshotsPlugin/init.server.lua

@@ -0,0 +1,12 @@
+local RunService = game:GetService("RunService")
+
+local EditModeMain = require(script.EditModeMain)
+local RunModeMain = require(script.RunModeMain)
+
+if RunService:IsEdit() then
+	EditModeMain(plugin)
+else
+	if RunService:IsClient() then
+		RunModeMain(plugin)
+	end
+end

bin/run-tests-snapshots.lua

@@ -0,0 +1,26 @@
+-- luacheck: globals __LEMUR__
+
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Roact = require(ReplicatedStorage.Roact)
+local TestEZ = require(ReplicatedStorage.TestEZ)
+
+Roact.setGlobalConfig({
+	["internalTypeChecks"] = true,
+	["typeChecks"] = true,
+	["elementTracing"] = true,
+	["propValidation"] = true,
+})
+local results = TestEZ.TestBootstrap:run(ReplicatedStorage.Roact, TestEZ.Reporters.TextReporter)
+
+local RoactSnapshots = ReplicatedStorage:WaitForChild("RoactSnapshots", 1)
+
+if not RoactSnapshots then
+    return nil
+end
+
+for _, snapshot in pairs(RoactSnapshots:GetChildren()) do
+    if snapshot:IsA("StringValue") then
+        print(("Snapshot:::<|%s|><|=>%s<=|>"):format(snapshot.Name, snapshot.Value))
+    end
+end

bin/spec.lua

@@ -6,6 +6,7 @@
 local LOAD_MODULES = {
 	{"src", "Roact"},
 	{"modules/testez/lib", "TestEZ"},
+	{"RoactSnapshots", "RoactSnapshots"},
 }
 
 -- This makes sure we can load Lemur and other libraries that depend on init.lua

bin/sync_snapshots.lua

@@ -0,0 +1,64 @@
+local lfs = require("lfs")
+
+local ROJO_PROJECT_FILE = "place.project.json"
+local TEST_FILE = "bin/run-tests-snapshots.lua"
+
+local SNAPSHOTS_FOLDER = "RoactSnapshots"
+local TEST_PLACE_FILE_NAME = "temp-snapshot-place.rbxlx"
+
+local function writeSnapshotFile(name, content)
+	lfs.mkdir(SNAPSHOTS_FOLDER)
+
+	local fileName = name .. ".lua"
+	local filePath = ("%s/%s"):format(SNAPSHOTS_FOLDER, fileName)
+
+	print("Writing", filePath)
+
+	local file = io.open(filePath, "w")
+	file:write(content)
+	file:close()
+end
+
+local function executeCommand(command)
+	print(command)
+	local handle = io.popen(command)
+	local line = handle:read("*l")
+	local output = {line}
+
+	while line do
+		line = handle:read("*l")
+		table.insert(output, line)
+	end
+
+	handle:close()
+
+	return table.concat(output, "\n")
+end
+
+print("Building test place")
+executeCommand(("rojo build %s -o %s"):format(
+	ROJO_PROJECT_FILE,
+	TEST_PLACE_FILE_NAME
+))
+
+print("Running run-in-roblox")
+local output = executeCommand(("run-in-roblox %s -s %s -t 100"):format(
+	TEST_PLACE_FILE_NAME,
+	TEST_FILE
+))
+
+print("Clean test place")
+os.remove(TEST_PLACE_FILE_NAME)
+
+print("Processing output...")
+
+local filteredOutput = output:gsub("\nSnapshot:::<|[%w_%-%.]+|><|=>.-<=|>", "")
+
+print(filteredOutput, "\n")
+
+for snapshotPattern in output:gmatch("Snapshot:::<|[%w_%-%.]+|><|=>.-<=|>") do
+	local name = snapshotPattern:match("Snapshot:::<|([%w_%-%.]+)|>")
+	local content = snapshotPattern:match("<|=>(.-)<=|>")
+
+	writeSnapshotFile(name, content)
+end