README.md in sewing_kit-0.92.1 vs README.md in sewing_kit-0.93.0
- old
+ new
@@ -1,10 +1,10 @@
# sewing_kit [](https://buildkite.com/shopify/sewing-kit-gem-ci)
Zero configuration, high performance front end development at organization scale.
-This document focuses on Rails integration. For details of `sewing-kit`'s configuration and usage, see the [sewing-kit documentation](/README.md).
+`sewing_kit` facilitates legacy Rails integration using ERB tags. For a more complete modern stack with performance-as-a-feature, consider [quilt_rails](https://github.com/Shopify/quilt/tree/master/gems/quilt_rails). For details of the `sewing-kit` node package's configuration and usage, see the [sewing-kit README](/README.md).
## Quick Start
Create a Rails project using `dev init` then:
@@ -66,10 +66,13 @@
└── ui
├─- index.js (renders React into the DOM)
├── styles (optional)
│ └── settings.scss (global vars and @polaris overrides)
│
+ └── tests (optional)
+ │ └── each-test.ts
+ │ └── setup.ts
└── components (optional)
├── App
│ ├── index.js
│ ├── App.js
│ └── tests
@@ -86,30 +89,106 @@
└── Home
├-─ index.js
└── Home.js
```
-## Which version of sewing-kit can I use?
-
-Assume that the sewing*kit gem's latest minor version requires \_at least* the same minor version of the sewing-kit package.
-
-If sewing-kit makes a breaking change, this gem's minor version will be bumped to match the required sewing-kit version.
-
-## Transitioning from sprockets-commoner
-
-It is currently not recommended to use `sprockets-commoner` and `sewing_kit` in the same project.
-Minimally, it is required that the project does not have its own `babel-*` libraries that `sewing-kit` currently has as [dependencies](https://github.com/Shopify/sewing-kit/blob/master/package.json#L97~L102).
-
## React Boilerplate
- Create a React app in `app/ui/App.js` ([example](https://github.com/Shopify/sewing-kit-gem-example/blob/master/app/ui/App.jsx))
- In an `erb` view, add a placeholder for React content ([example](https://github.com/Shopify/sewing-kit-gem-example/blob/master/app/views/home/index.html.erb#L4))
- In `index.js`, render a React component into the placeholder element ([example](https://github.com/Shopify/sewing-kit-gem-example/blob/master/app/ui/index.js))
- Use `sewing_kit_script_tag`/`sewing_kit_link_tag` helpers to link erb/js ([example](https://github.com/Shopify/sewing-kit-gem-example/blob/master/app/views/layouts/application.html.erb#L8))
+## Testing the front end
+
+For fast tests with consistent results, test front-end components using Jest instead of Rails integration tests.
+
+Use [`sewing-kit test`](https://github.com/Shopify/sewing-kit/blob/master/docs/commands/test.md#L3) to run all `.test.tsx` files in the `app/ui` directory. [Jest](https://jestjs.io) is used as a test runner, with customization available via [its sewing-kit plugin](https://github.com/Shopify/sewing-kit/blob/master/docs/plugins/jest.md).
+
+### Testing React
+
+For testing React applications we provide and support [`@shopify/react-testing`](https://github.com/Shopify/quilt/tree/master/packages/react-testing).
+
+#### Example
+
+Given a component `MyComponent.tsx`
+
+```tsx
+// app/components/MyComponent/MyComponent.tsx
+export function MyComponent({name}: {name: string}) {
+ return <div>Hello, {name}!</div>;
+}
+```
+
+A test would be written using Jest and `@shopify/react-testing`'s `mount` feature.
+
+```tsx
+// app/components/MyComponent/tests/MyComponent.test.tsx
+import {MyComponent} from '../MyComponent';
+
+describe('MyComponent', () => {
+ it('greets the given named person', () => {
+ const wrapper = mount(<MyComponent name="Kokusho" />);
+
+ // toContainReactText is a custom matcher provided by @shopify/react-testing/matchers
+ expect(wrapper).toContainReactText('Hello, Kokusho');
+ });
+});
+```
+
+### Test setup files
+
+By default, the jest plugin will look for test setup files under `/app/ui/tests`.
+
+`setup` can be used to add any custom polyfills needed for the testing environment.
+
+```tsx
+// app/ui/tests/setup.ts
+
+import 'isomorphic-fetch';
+import 'raf/polyfill';
+import {URL, URLSearchParams} from 'url';
+
+(global as any).URL = URL;
+(global as any).URLSearchParams = URLSearchParams;
+```
+
+`each-test` can be used for any logic that needs to run for each individual test suite. Any setup logic that needs to happen with `jest` globals in scope, such as importing custom matchers, should also be done here.
+
+```tsx
+// app/ui/tests/each-test.ts
+
+// we cannot import these in `setup` because `expect` will not be defined
+import '@shopify/react-testing/matchers';
+
+beforeAll(() => {
+ console.log('I will run before every test suite');
+});
+
+beforeEach(() => {
+ console.log('I will run before every test case');
+});
+
+afterEach(() => {
+ console.log('I will run after every test case');
+});
+
+afterAll(() => {
+ console.log('I will run after every test suite');
+});
+```
+
+For more complete documentation of the jest plugin see [it's documentation](/docs/plugins/jest.md).
+
## FAQ
+### Which version of sewing-kit can I use?
+
+Assume that the sewing*kit gem's latest minor version requires \_at least* the same minor version of the sewing-kit package.
+
+If sewing-kit makes a breaking change, this gem's minor version will be bumped to match the required sewing-kit version.
+
### How can I fix production builds that are failing due to missing devDependencies?
By moving everything into `package.json#dependencies`. This is necessary because Rails 5.2 prunes `devDependencies` during asset compilation.
### How can I test a production verison of my changes?
@@ -120,5 +199,9 @@
NODE_ENV=production bundle exec rake assets:precompile
NODE_ENV=production SK_SIMULATE_PRODUCTION=1 dev run
```
Note that code changes will not be automatically recompiled in this state. After verifying production behaviour, run `bundle exec rake assets:clobber` to get back to development mode.
+
+### My project is using `sprockets-commenoner`, can I use sewing_kit too?
+
+No. sprockets-commoner uses an outdated Babel version, and is no longer compatible with sewing-kit.