Shallow wrapper #223

jeparlefrancais · 2019-07-02T22:51:27Z

Closes #189 and closes #156.

This PR adds a new feature to Roact: the ability to create snapshots from a Roact tree. Combine to that, the concept of shallow rendering is used to help making as small snapshots as possible.

How it works:

Mounts an element with Roact.mount to get a VirtualTree (as usual)
Get a ShallowWrapper from VirtualTree:getShallowWrapper()
That wrapper is used to make assertions on element kind, props or to find children of a component with some constraints (or simulate events later maybe). It is also possible to generate a snapshot from the ShallowWrapper.

This approach does not have much internal representation, it just uses the VirtualNode to find what it needs. It currently supports fragments.

I have written some documentation about the API and also how snapshots and shallow rendering can be used.

Checklist before submitting:

Commit snapshot files
Added entry to CHANGELOG.md
Added/updated relevant tests
Added/updated documentation

coveralls · 2019-07-02T23:21:59Z

Coverage increased (+1.3%) to 94.85% when pulling 780fc4f on jeparlefrancais:shallow-wrapper into 986c1d5 on Roblox:master.

jeparlefrancais · 2019-07-19T21:06:40Z

So this just turned into a massive PR, more oriented towards generating snapshots.

The ShallowWrapper will need a better name, but I'm still not sure about what it should be (open for suggestions!)

The current API for snapshots is

local wrapper = Roact.shallow(element, {
    depth = 1,
})

wrapper:toMatchSnapshot("snapshot identifier")

This would generate a snapshot serialized in a ModuleScript in a folder named "RoactSnapshots" under ReplicatedStorage

MisterUncloaked · 2019-08-02T00:37:34Z

src/ShallowWrapper.lua

+	return results
+end
+
+function ShallowWrapper:findUnique(constraints)


Do we need convenience methods like this? I'm trying to imagine when developers will want to use this versus relying on snapshot matching.

We decided to keep this for cases where we want to remove some scaffolding injected by things like mock providers

MisterUncloaked · 2019-08-02T00:43:52Z

Overall I really like the idea of snapshotting the shallow representation of components versus how snapshots are traditionally done. It keeps the snapshots smaller, and ultimately removes the need for a lot of boilerplate assertions typically found when testing with shallow rendering.

src/snapshot.spec.lua

src/VirtualTree.lua

src/assertDeepEqual.lua

src/VirtualTree.lua

MisterUncloaked · 2019-08-02T22:04:48Z

src/ShallowWrapper.lua

+			component = element.component,
+		}
+	else
+		error(('shallow wrapper does not support element of kind %q'):format(tostring(kind)))


reminder for us to document the types we support when we get to writing documentation for snapshot testing

MisterUncloaked · 2019-08-02T22:27:12Z

src/ShallowWrapper.lua

+function ShallowWrapper.new(virtualNode, maxDepth)
+	virtualNode = findNextVirtualNode(virtualNode, maxDepth)
+
+	local wrapper = {


to simplify this class, the wrapper could just be the node + the depth, and we could remove some of the mapping we are doing from the virtual node interface to the shallow

MisterUncloaked · 2019-08-02T22:27:59Z

src/ShallowWrapper.lua

+	end
+end
+
+local function filterProps(props)


it could be simpler to just not filter the props in the shallow at all

I want remove the Roact.Children key from the props when it's there. That is because it makes it easier to assert your props. Intuitively, it matches what you put in the props argument of Roact.createElement.

src/ShallowWrapper.lua

MisterUncloaked · 2019-08-02T22:36:08Z

src/ShallowWrapper.lua

+	local results = {}
+
+	for _, childVirtualNode in pairs(self._virtualNodeChildren) do
+		getChildren(childVirtualNode, results, self._childrenMaxDepth)


instead of using a non member function, this could be a bit simpler:

local childWrapper = ShallowWrapper.new( childVirtualNode, self._childrenMaxDepth ) childWrapper:getChildren() table.insert(results, childWrapper)

this would need the fragment check as well if we got rid of the other function

The thing I don't like with the member function is that I would have to copy back the elements from the getChildren call into the result table recursively. Do you think it would be better to just go for clarity at this point? I have not benchmark anything yet so I don't have numbers about what is the performance gain

Perf is a good point, but I wonder if that concern goes away if we redefine depth such that we're building more deeply nested tables instead of coalescing the children at various levels of the tree to be the shallow children.

…ording

Shallow Rendering Documentation Edits

In order to prevent leaking the ElementKind symbols, they have been removed from the ShallowWrapper API

ZoteTheMighty

Still need to look at the docs a bit more.

I think most of this approach is sound, and really powerful! I am still hopeful, though, that we can find a way to better isolate a lot of this from the main Roact repo.

ZoteTheMighty · 2019-08-20T21:13:55Z

docs/api-reference.md

@@ -32,21 +32,21 @@ Creates a new Roact fragment with the provided table of elements. Fragments allo

 ### Roact.mount
 ```
-Roact.mount(element, [parent, [key]]) -> RoactTree
+Roact.mount(element, [parent, [key]]) -> VirtualTree


I don't know if I agree with changing the terminology here. Ideally, we should expose as little internal vocabulary as possible in order to define what snapshots are and what they do.

I can switch it back to RoactTree, it's just that the Type we are going to expose in #230 is called VirtualTree. So maybe it could be renamed in that other PR?

That's a good question! I didn't realize we were exposing it in that PR. We should probably discuss this with @LPGhatguy.

My thoughts are still that VirtualTree probably means less to users, but maybe there's another better alternative too.

Yes I agree that the term VirtualTree might be questionable to users, we should probably solves this in #230 if it's about to be merged first.

docs/api-reference.md

ZoteTheMighty · 2019-08-20T21:27:16Z

docs/api-reference.md

+```
+
+If we shallow-render the `MainComponent`, the default depth will not render the CoolComponent.


This seems like an explanation of how render depth works, not an explanation of what getHostObject does

I wanted to explain when getHostObject can return nil or not, but yep it does include talking a bit about depth... Should I remove it or not?

ZoteTheMighty · 2019-08-20T22:33:58Z

docs/scripts/sync-snapshots-with-lua.md

+
+	writeSnapshotFile(name, content)
+end
+```


Do we need both this and the python version?

I made both originally because with Roact, lemur runs with lua so I assumed people would prefer lua to sync stuff. And I have made the python version because uiblox is already using python for it's image packaging thing!

So I don't know if we need both, but it's more convenient to offer it I think

ZoteTheMighty · 2019-08-20T22:34:33Z

docs/scripts/sync-snapshots-with-python.md

+
+---
+
+Using a python interpreter (compatible with 2 or 3), put the following script in a file and run it.


Why don't we just include the script somewhere?

src/shallow/Snapshot/Serialize/Serializer.lua

ZoteTheMighty · 2019-08-21T16:51:51Z

src/shallow/Snapshot/Serialize/Snapshot.lua

+	local kind = ElementKind.fromComponent(wrapperComponent)
+
+	local typeData = {
+		kind = kind,


I wonder if we even still need this in the snapshot, or if there's sufficient data without it.

I made a longer comment above, but it's useful for function components, because I can't serialize their function. It's only going to show up as a AnonymousFunction symbol

ZoteTheMighty · 2019-08-21T17:15:16Z

src/shallow/validateShallowOptions.lua

+	end
+
+	return true
+end


This solution seems way overzealous for something like this. Is this in the name of future proofing? I worry it's getting a little out of hand.

Yes at some point I add three parameters (depth, hostKey and hostParent) so I felt like it would be good to make sure there are no typos and mismatched types. But yeah right now with only the depth it looks a bit like nuking a fly.

Should I still keep the dictionary as a parameter for future proofing, but remove the validation?

I think when it comes to stuff like this, we need to strike a balance between predicting how our API might change in the future and just giving up and making it a table. Tables are fine in a lot of cases but they feel really awkward when there are only one or two elements.

Personally, I'm okay with the public shallow function just taking depth as its second argument. It doesn't seem like we would wildly change this function's signature anytime soon. What do you think?

Yes and you make me realise that since we are now mounting with Roact.mount, the shallow function is not public anymore. I use it as en entry point from Roact to the shallow module.

jeparlefrancais added 3 commits July 2, 2019 08:51

Implement shallow wrapper

72c6921

Add depth to children wrapper

2b7dde9

Support fragments

f57fa89

jeparlefrancais added 4 commits July 9, 2019 10:50

Filter children prop from shallow.props

7ee2939

Add ShallowWrapper:getChildren()

45b48da

Split deep equal comparison from assertDeepEqual

8450335

Add snapshot serialization

a1f914f

jeparlefrancais force-pushed the shallow-wrapper branch from 5425c67 to a1f914f Compare July 19, 2019 20:50

jeparlefrancais added 8 commits July 23, 2019 14:55

Add ref serialization

17d8146

Format floats with maximum 7 decimals

4183766

Remove Roact.shallow for virtualTree method

830c0b6

Rename failed snapshot to new snapshot

39eae67

Update snapshot tests

16e1ba0

Add snapshot tests

c81d22f

Update snapshot tests

9b09be8

Remove missing lemur events

5944bf3

jeparlefrancais marked this pull request as ready for review July 30, 2019 21:43