react

Currently, Sprout runs each fixture with a known set of inputs and annotations. Sprout compares execution outputs (i.e. return values and console logs) of original source code and the corresponding Forget-transformed version. We hope to add fuzzing capabilities to Sprout, synthesizing sets of program inputs based on type and/or effect annotations.

Sprout is now enabled for all fixtures! If Sprout cannot execute your fixture due to some technical limitations, add your fixture to SproutTodoFilter.ts with a comment explaining why.

Sprout CLI

Sprout can be run from packages/babel-plugin-react-forget. When adding new fixtures to Sprout, please check that fixture outputs look reasonable with yarn sprout --filter --verbose.

# rebuild when sprout or babel-plugin-react-forget changes
$ yarn sprout:build

# evaluate all test fixtures not listed in SproutTodoFilter
$ yarn sprout

# show all sprout options
$ yarn sprout --help
Options:
  --sync     Run compiler in main thread.
                          [boolean] [default: false]
  --filter   Evaluate fixtures in filter mode.
                          [boolean] [default: false]
  --verbose  Print all fixture outputs and logs.
                          [boolean] [default: false]

Sprout can be run in filter mode with yarn sprout --filter. Just like Snap, Sprout expects babel-plugin-react-forget/testfilter.txt be formatted as such.

first line: // @only or // @skip
all other lines: a test fixture name, i.e. the relative path from the compiler fixtures dir, without a .js or .expect.md extension.

Example:

// @only
console-readonly
constant-propagate-global-phis
dce-loop

Adding fixtures to Sprout

1. Annotate fixtures.

Each fixture test executed by Sprout needs to export const FIXTURE_ENTRYPOINT object with the following type signature.

type FixtureEntrypoint<T> = {
  // function to be invoked
  fn: ((...params: Array<T>) => any),
  // params to pass to fn
  // (if `fn` is a react component, this should be an array
  // with exactly one element -- props)
  params: Array<T>,
}

Example:

// test.js
function MyComponent(props) {
  return <div>{props.a + props.b}</div>;
}
export const FIXTURE_ENTRYPOINT = {
  fn: MyComponent,
  params: [{a: "hello ", b: "world"}],
};

2. Import / define helper functions.

Prefer importing helper functions for readability and simplicity.
Fixtures that require helper functions with specific types or mutability can define their own within the same fixture file.

// test.js
import { addOne } from 'shared-runtime';

function customHelper(val1, val2) {
  // This directive is important, as helper functions don't
  // always follow the rules of React.
  "use no forget";
  // ...
}

// ...

Notes

If your fixture needs to import from an external module, we currently only support importing from react (see Milestones todo list).
Any fixture can use React hooks, but they need to be first imported. We may later enforce that only isComponent: true fixtures can use React hooks.
```
import {useState} from 'react';
```
If your fixture wants to export multiple functions to Sprout to run, please split up the fixture into multiple files (e.g. test-case-1, test-case-2, etc).
Sprout currently runs each fixture in an iife to prevent variable collisions, but it does not run fixtures in isolation. Please do not mutate any external state in fixtures.
Sprout does not run fixtures listed in SproutTodoFilter.ts, even in filter mode.

Milestones:

[✅] Render fixtures with React runtime / testing-library/react.
[✅] Make Sprout CLI -runnable and report results in process exit code.
[✅] Enable Sprout by default and run it in the Github Actions pipeline.
[🚧] Make all existing test fixtures Sprout compatible (see SproutTodoFilter.ts). This involves each fixture being annotated with FIXTURE_ENTRYPOINT and using shared functions and/or defining its own helpers.
- 77 done, ~410 to go
[✅] (optional) Store Sprout output as snapshot files. i.e. each fixture could have a fixture.js, fixture.snap.md, and fixture.sprout.md.
[✅] Add support for fbt.