Merge pull request #159 from oslabs-beta/master

Master

Author: Ergi516

.gitignore

@@ -1,4 +1,4 @@
-node_modules
+/node_modules
 .DS_Store
 src/extension/build/bundles
 package/reactime-*.tgz
@@ -8,4 +8,5 @@ coverage
 src/extension/build.zip
 src/extension/build.crx
 src/extension/build.pem
-bower_components
+bower_components
+sandboxes/manual-tests/NextJS/.next

package/astParser.js

@@ -1,7 +1,8 @@
-/* eslint-disable no-inner-declarations */
-const acorn = require('acorn'); // javascript parser
+/* eslint-disable no-inner-declarations, no-loop-func */
 // eslint-disable-next-line import/newline-after-import
+const acorn = require('acorn'); // javascript parser
 const jsx = require('acorn-jsx');
+
 const JSXParser = acorn.Parser.extend(jsx());
 
 // Helper function to grab the getters/setters from `elementType`
@@ -11,6 +12,7 @@ module.exports = elementType => {
   const hookState = {};
 
   while (Object.hasOwnProperty.call(ast, 'body')) {
+    let tsCount = 0; // Counter for the number of TypeScript hooks seen (to distinguish in masterState)
     ast = ast.body;
     const statements = [];
 
@@ -26,7 +28,19 @@ module.exports = elementType => {
       body.forEach(elem => {
         if (elem.type === 'VariableDeclaration') {
           elem.declarations.forEach(hook => {
-            statements.push(hook.id.name);
+            // * TypeScript hooks appear to have no "VariableDeclarator"
+            // * with id.name of _useState, _useState2, etc...
+            // * hook.id.type relevant for TypeScript applications
+            // *
+            // * Works for useState hooks
+            if (hook.id.type === 'ArrayPattern') {
+              hook.id.elements.forEach(hook => {
+                statements.push(hook.name);
+                // * Unshift a wildcard name to achieve similar functionality as before
+                statements.unshift(`_useWildcard${tsCount}`);
+                tsCount += 1;
+              });
+            } else statements.push(hook.id.name);
           });
         }
       });

package/index.js

@@ -1,3 +1,9 @@
+/**
+ * 'reactime' module has a single export
+ * @function linkFiber
+ */
+
+// * State snapshot object initialized here
 const snapShot = { tree: null };
 
 const mode = {
@@ -21,10 +27,11 @@ function getRouteURL(node) {
   }
 }
 
-window.addEventListener('message', ({ data: { action, payload } }) => { // runs automatically twice per second with inspectedElement
+// * Event listener for time-travel actions
+window.addEventListener('message', ({ data: { action, payload } }) => {
   switch (action) {
     case 'jumpToSnap':
-      timeJump(payload);
+      timeJump(payload); // * This sets state with given payload
       // Get the pathname from payload and add new entry to browser history
       // MORE: https://developer.mozilla.org/en-US/docs/Web/API/History/pushState
       window.history.pushState('', '', getRouteURL(payload));

package/linkFiber.js

@@ -1,9 +1,46 @@
+/**
+ * This file contains core module functionality.
+ *
+ * It exports an anonymous
+ * @function
+ * that is invoked on
+ * @param snap --> Current snapshot
+ * @param mode --> Current mode (jumping i.e. time-traveling, locked, or paused)
+ * and @returns a function to be invoked on the rootContainer HTMLElement
+ *
+ * @function updateSnapShotTree
+ * --> Middleware #1: Updates snap object with latest snapshot
+ *
+ * @function sendSnapshot
+ * --> Middleware #2: Gets a copy of the current snap.tree and posts a message to the window
+ *
+ * @function changeSetState
+ * @param component : stateNode property on a stateful class component's FiberNode object
+ * --> Binds class component setState method to the component
+ * --> Injects middleware into class component's setState method
+ *
+ * @function changeUseState
+ * @param component : memoizedState property on a stateful functional component's FiberNode object
+ * --> Binds functional component dispatch method to the component
+ * --> Injects middleware into component's dispatch method
+ * Note: dispatch is hook equivalent to setState()
+ *
+ * @function traverseHooks
+ * @param memoizedState : memoizedState property on a stateful fctnl component's FiberNode object
+ * --> Helper function to traverse through memoizedState
+ * --> Invokes @changeUseState on each stateful functional component
+ *
+ * @function createTree
+ * @param currentFiber : a FiberNode object
+ * --> Recursive function to traverse from FiberRootNode and create
+ *     an instance of custom Tree class and build up state snapshot
+ */
+
 /* eslint-disable no-underscore-dangle */
 /* eslint-disable func-names */
 /* eslint-disable no-use-before-define */
 /* eslint-disable no-param-reassign */
-// links component state tree to library
-// changes the setState method to also update our snapshot
+
 const Tree = require('./tree');
 const astParser = require('./astParser');
 const { saveState } = require('./masterState');
@@ -14,80 +51,80 @@ module.exports = (snap, mode) => {
   let concurrent = false; // flag to check if we are in concurrent mode
 
   function sendSnapshot() {
-    // don't send messages while jumping or while paused
+    // Don't send messages while jumping or while paused
     // DEV: So that when we are jumping to an old snapshot it
-    // wouldn't think we want to create new snapshots
     if (mode.jumping || mode.paused) return;
     const payload = snap.tree.getCopy();
-    // console.log('payload', payload);
     window.postMessage({
       action: 'recordSnap',
       payload,
     });
   }
 
   function changeSetState(component) {
-    // check that setState hasn't been changed yet
     if (component.setState.linkFiberChanged) return;
-    // make a copy of setState
+
+    // Persist the old setState and bind to component so we can continue to setState({})
     const oldSetState = component.setState.bind(component);
-    // replace component's setState so developer doesn't change syntax
-    // component.setState = newSetState.bind(component);
+
     component.setState = (state, callback = () => {}) => {
-      // don't do anything if state is locked
-      // UNLESS we are currently jumping through time
+      // Don't do anything if state is locked UNLESS we are currently jumping through time
       if (mode.locked && !mode.jumping) return;
-      // continue normal setState functionality, except add sending message middleware
+      // Continue normal setState functionality, with middleware in callback
       oldSetState(state, () => {
         updateSnapShotTree();
         sendSnapshot();
         callback.bind(component)();
       });
     };
+    // Set a custom property to ensure we don't change this method again
     component.setState.linkFiberChanged = true;
   }
 
   function changeUseState(component) {
     if (component.queue.dispatch.linkFiberChanged) return;
-    // store the original dispatch function definition
+
+    // Persist the old dispatch and bind to component so we can continue to dispatch()
     const oldDispatch = component.queue.dispatch.bind(component.queue);
-    // redefine the dispatch function so we can inject our code
+
     component.queue.dispatch = (fiber, queue, action) => {
-      // don't do anything if state is locked
       if (mode.locked && !mode.jumping) return;
       oldDispatch(fiber, queue, action);
+      // * Uncomment setTimeout to prevent snapshot lag-effect
+      // * (i.e. getting the prior snapshot on each state change)
       // setTimeout(() => {
       updateSnapShotTree();
       sendSnapshot();
       // }, 100);
     };
+    // Set a custom property to ensure we don't change this method again
     component.queue.dispatch.linkFiberChanged = true;
   }
 
-  // Helper function to traverse through the memoized state
   // TODO: WE NEED TO CLEAN IT UP A BIT
   function traverseHooks(memoizedState) {
     // Declare variables and assigned to 0th index and an empty object, respectively
     const memoized = {};
     let index = 0;
     astHooks = Object.values(astHooks);
-    // while memoizedState is truthy, save the value to the object
+    // While memoizedState is truthy, save the value to the object
     while (memoizedState && memoizedState.queue) {
-      // prevents useEffect from crashing on load
+      // // prevents useEffect from crashing on load
       // if (memoizedState.next.queue === null) { // prevents double pushing snapshot updates
       changeUseState(memoizedState);
       // }
       // memoized[astHooks[index]] = memoizedState.memoizedState;
       memoized[astHooks[index]] = memoizedState.memoizedState;
       // Reassign memoizedState to its next value
       memoizedState = memoizedState.next;
-      // Increment the index by 2
+      // See astParser.js for explanation of this increment
       index += 2;
     }
     return memoized;
   }
 
   function createTree(currentFiber, tree = new Tree('root')) {
+    // Base case: child or sibling pointed to null
     if (!currentFiber) return tree;
 
     const {
@@ -99,19 +136,17 @@ module.exports = (snap, mode) => {
     } = currentFiber;
 
     let nextTree = tree;
-    // check if stateful component
+
+    // Check if stateful component
     if (stateNode && stateNode.state) {
-      // add component to tree
-      nextTree = tree.appendChild(stateNode);
-      // change setState functionality
-      changeSetState(stateNode);
+      nextTree = tree.appendChild(stateNode); // Add component to tree
+      changeSetState(stateNode); // Change setState functionality
     }
-    // Check if the component uses hooks
-    // console.log("memoizedState", memoizedState);
 
+    // Check if the component uses hooks
     if (
-      memoizedState &&
-      Object.hasOwnProperty.call(memoizedState, 'baseState')
+      memoizedState
+      && Object.hasOwnProperty.call(memoizedState, 'baseState')
     ) {
       // 'catch-all' for suspense elements (experimental)
       if (typeof elementType.$$typeof === 'symbol') return;
@@ -123,18 +158,19 @@ module.exports = (snap, mode) => {
       memoizedState.traversed = traverseHooks(memoizedState);
       nextTree = tree.appendChild(memoizedState);
     }
-    // iterate through siblings
+
+    // Recurse on siblings
     createTree(sibling, tree);
-    // iterate through children
+    // Recurse on children
     createTree(child, nextTree);
 
     return tree;
   }
-  // runs when page initially loads
-  // but skips 1st hook click
+
+  // ! BUG: skips 1st hook click
   async function updateSnapShotTree() {
     let current;
-    // if concurrent mode, grab current.child'
+    // If concurrent mode, grab current.child
     if (concurrent) {
       // we need a way to wait for current child to populate
       const promise = new Promise((resolve, reject) => {
@@ -152,6 +188,7 @@ module.exports = (snap, mode) => {
   }
 
   return async container => {
+    // Point fiberRoot to FiberRootNode
     if (container._internalRoot) {
       fiberRoot = container._internalRoot;
       concurrent = true;
@@ -160,12 +197,13 @@ module.exports = (snap, mode) => {
         _reactRootContainer: { _internalRoot },
         _reactRootContainer,
       } = container;
-      // only assign internal root if it actually exists
+      // Only assign internal root if it actually exists
       fiberRoot = _internalRoot || _reactRootContainer;
     }
 
     await updateSnapShotTree();
-    // send the initial snapshot once the content script has started up
+    // Send the initial snapshot once the content script has started up
+    // This message is sent from contentScript.js in chrome extension bundles
     window.addEventListener('message', ({ data: { action } }) => {
       if (action === 'contentScriptStarted') sendSnapshot();
     });

package/timeJump.js

@@ -1,7 +1,19 @@
+/**
+ * This file contains necessary functionality for time-travel feature
+ *
+ * It exports an anonymous
+ * @function
+ * that is invoked on
+ * @param target --> a target snapshot portraying some past state
+ * and recursively sets state for any stateful components.
+ *
+ */
+
 /* eslint-disable no-param-reassign */
-// traverses given tree by accessing children through coords array
+
 const { returnState } = require('./masterState');
 
+// Traverses given tree by accessing children through coords array
 function traverseTree(tree, coords) {
   let curr = tree;
   coords.forEach(coord => {
@@ -11,23 +23,33 @@ function traverseTree(tree, coords) {
 }
 
 module.exports = (origin, mode) => {
-  // recursively change state of tree
+  // Recursively change state of tree
   function jump(target, coords = []) {
     const originNode = traverseTree(origin.tree, coords);
-    // set the state of the origin tree if the component is stateful
+
+    // Set the state of the origin tree if the component is stateful
     if (originNode.component.setState) {
-      originNode.component.setState(target.state, () => {
-        // iterate through new children once state has been set
+      // * Use the function argument when setting state to account for any state properties
+      // * that may not have existed in the past
+      originNode.component.setState(prevState => {
+        Object.keys(prevState).forEach(key => {
+          if (target.state[key] === undefined) {
+            target.state[key] = undefined;
+          }
+        });
+        return target.state;
+      }, () => {
+        // Iterate through new children once state has been set
         target.children.forEach((child, i) => {
           jump(child, coords.concat(i));
         });
       });
     } else {
-      // if component uses hooks, traverse through the memoize tree
+      // If component uses hooks, traverse through the memoize tree
       let current = originNode.component;
       let index = 0;
       const hooks = returnState();
-      // while loop through the memoize tree
+      // While loop through the memoize tree
       while (current && current.queue) { // allows time travel with useEffect
         current.queue.dispatch(target.state[hooks[index]]);
         // Reassign the current value
@@ -38,7 +60,7 @@ module.exports = (origin, mode) => {
   }
 
   return target => {
-    // setting mode disables setState from posting messages to window
+    // * Setting mode disables setState from posting messages to window
     mode.jumping = true;
     jump(target);
     setTimeout(() => {

sandboxes/README.md

@@ -0,0 +1,22 @@
+# Reactime End-to-End Testing
+
+This folder contains automated tests as well as manual tests. The automated Jest / Puppeteer tests can be run by issuing the npm test command from within the root of the automated-tests directory.
+
+Manual tests have been created for both Concurrent Mode and NextJS. These sandboxes can be launched by issuing the npm start command from within either of the directories inside of the manual-tests folder. Note that for the NextJS sandbox, npm run build should be issued before npm start. These manual sandboxes can also be automated by using the same approach as the automated testing sandboxes.
+
+Automated Tests
+
+- useState
+- useEffect
+- useContext
+- useMemo
+- Redux
+- React Router
+- setState
+- Conditional setState
+- componentDidMount
+
+Manual Tests
+
+- Concurrent Mode / Suspense
+- Next.js