add docs + prepare for release

Author: Raice Hannay

.gitignore

@@ -11,6 +11,7 @@ lib
 node_modules
 npm-debug.log
 yarn.error.l
+*.tgz
 
 #IDEs
 .idea

.prettierignore

@@ -1,5 +1,6 @@
 coverage/*
 dist/*
+docs/*
 package.json
 yarn.lock
 README.md

README.md

@@ -0,0 +1,53 @@
+React Test Wrapper
+==================
+
+The intention of this package is to provide a simple, clean way of setting up your React components
+for unit tests, to reduce test setup boilerplate code, whilst automatically inferring your component
+TypeScript definitions (props, instance methods etc) to avoid needing to manually import types and
+retype definitions in your tests and also providing better inline IDE autocomplete/validation support.
+
+The classes provided are also able to be extended to add to the API that's available, if your
+project requires additional functionality as part of your component test setup.
+
+The concept behind it is that you can create a single instance of the wrapper class at the top of
+your test file and define the defaults to use there, then in each test scenario you can reference
+the single instance and define the scenario-specific props/children etc. chaining the public methods,
+then finally calling the `mount`, `shallow` or `render` method to return the Enzyme wrapper and merged props.
+
+The scenario-specific definitions are reset each time you call `mount`, `render` or `shallow`, which
+will ensure it reverts back to only the defaults set at the top and prevents scenario data from leaking
+between tests.
+
+For example:
+```typescript jsx
+const component = new Wrapper(SomeComponent)
+  .withDefaultChildren(<div className="Child" />)
+  .withDefaultProps({
+    prop1: "Default value 1",
+    prop2: "Default value 2"
+  });
+
+describe("when testing a scenario", () => {
+  const wrapper = component
+    .withProps({
+      prop1: "Scenario value 1"
+    })
+    .mount();
+
+  it("uses the scenario-specific value for prop1", () => {
+    expect(wrapper.find(".SomeComponent--prop1").text()).toBe("Scenario value 1");
+  });
+
+  it("uses the default value for prop2", () => {
+    expect(wrapper.find(".SomeComponent--prop2").text()).toBe("Default value 1");
+  });
+});
+```
+
+
+The classes
+-----------
+
+- [`Wrapper`](./docs/Wrapper.md)
+- [`WrapperWithIntl`](./docs/WrapperWithIntl.md)
+- [`WrapperWithRedux`](./docs/WrapperWithRedux.md)

docs/Wrapper.md

@@ -0,0 +1,71 @@
+`Wrapper`
+=========
+
+This is the base class which is used for basic presentational components. The other classes provided
+extend this one, so all methods defined on this class are also available on the others.
+
+As with all of these classes, you can extend it to implement your own additional functionality.
+
+Public read-only properties
+---------------------------
+
+### `props`
+The props the component was mounted with. Useful for avoiding needing to declare local variables
+for later assertion reference - especially mock function instances.
+
+
+Public methods
+--------------
+
+### `withDefaultChildren`
+Sets the default children to be used for the wrapper instance.
+
+### `withDefaultProps`
+Sets the default props to be used for the wrapper instance.
+
+### `withChildren`
+Sets the scenario-specific children to be used - cleared after `mount`, `render` or `shallow` are called.
+
+### `withProps`
+Sets the scenario-specific props to be used - cleared after `mount`, `render` or `shallow` are called.
+
+### `mount`
+Mounts the component with the Enzyme `mount` function, using the currently-set data.
+Returns a `ReactWrapper` instance.
+
+### `render`
+Mounts the component with the Enzyme `render` function, using the currently-set data.
+Returns a `ShallowWrapper` instance.
+
+### `shallow`
+Mounts the component with the Enzyme `shallow` function, using the currently-set data.
+Returns a `Cheerio` instance.
+
+How to extend
+-------------
+
+To extend this class to implement your own setup functionality, you can do so as shown in the
+example below.
+
+There's a `WrappingComponent` property on the `Wrapper` class that will automatically be used by
+`mount`, `render` and `shallow` when it's defined, to wrap the component being tested.
+This is very useful when testing components that require some form of context provider component to
+exist in the React tree.
+
+```typescript jsx
+import * as React from "react";
+import { Wrapper as BaseWrapper } from "react-test-wrapper";
+
+export class WrapperWithCustomStuff<
+  C extends React.ComponentType<any>,
+  P extends React.ComponentProps<C> = React.ComponentProps<C>
+> extends BaseWrapper<C, P> {
+  protected WrappingComponent: React.FC = ({ children }) => (
+    <SomeProviderComponent>
+      {children}
+    </SomeProviderComponent>
+  );
+
+  // Add custom properties and methods here
+}
+```

docs/WrapperWithIntl.md

@@ -0,0 +1,34 @@
+`WrapperWithIntl`
+=================
+
+This abstract class has a `WrappingComponent` defined which wraps the component in an `IntlProvider`,
+passing in `intlProviderProps`.
+
+To use this class, you have to extend it and define your own `intlProviderProps` to set your own
+`messages` etc.
+
+
+Public methods
+--------------
+The public methods are identical to the base [`Wrapper`](./Wrapper.md) class.
+
+
+How to extend for use in your project
+-------------------------------------
+
+```typescript jsx
+import * as React from "react";
+import { IntlConfig } from "react-intl";
+import { WrapperWithIntl as BaseWrapper } from "react-test-wrapper";
+
+import messages from "./locales/en-NZ";
+
+export class WrapperWithIntl<
+  C extends React.ComponentType<any>,
+  P extends React.ComponentProps<C> = React.ComponentProps<C>
+> extends BaseWrapper<C, P> {
+  protected intlProviderProps: Partial<IntlConfig> = {
+    messages
+  };
+}
+```

docs/WrapperWithRedux.md

@@ -0,0 +1,67 @@
+`WrapperWithRedux`
+=================
+
+This abstract class has a `WrappingComponent` defined which wraps the component in a Redux `Provider`,
+passing in the return value from the `createStore` method.
+
+To use this class, you have to extend it and define your own `createStore` method to return an
+instance of your Redux store, using the `initialState` and `middlewares` that this class provides -
+it is important to ensure that your store uses these, because if it disregards them, none of the
+methods this class provides will function.
+
+
+Public read-only properties
+---------------------------
+
+### `reduxHistory`
+An array of actions that have been dispatched, used when asserting that actions have been
+dispatched as expected during interactions or in the component lifecycle.
+
+### `store`
+The instance of the Redux store used. However, this is only available after calling `mount`.
+If accessed prior to mounting your component, it will be `undefined`.
+
+
+Public methods
+--------------
+
+In addition to the public methods provided by the base [`Wrapper`](./Wrapper.md) class, the following
+methods are available.
+
+Note:
+While technically the `render` and `shallow` methods are accessible, they will throw an error
+due to issues with the integration of the Redux store provider.
+
+`render` doesn't work due to its use of `useLayout`, which doesn't work in a test environment.
+`shallow` isn't useful due to it only mounting the Redux provider component.
+
+### `withDefaultReduxState`
+Sets the default Redux store state to be used for the wrapper instance.
+
+### `withReduxState`
+Sets the scenario-specific Redux store state to be used - cleared after `mount`, `render` or `shallow` are called.
+
+
+How to extend for use in your project
+-------------------------------------
+
+```typescript jsx
+import * as React from "react";
+import { IntlConfig } from "react-intl";
+import { WrapperWithRedux as BaseWrapper } from "react-test-wrapper";
+
+import { createStore } from "../store/createStore";
+
+class Wrapper<
+  C extends React.ComponentType<any>,
+  S extends {} = TStoreState,
+  P extends React.ComponentProps<C> = React.ComponentProps<C>
+> extends WrapperWithRedux<C, S, P> {
+  protected createStore(
+    initialState: DeepPartial<S>,
+    middlewares: Middleware[]
+  ) {
+    return createStore(initialState, middlewares);
+  }
+}
+```

package.json

@@ -21,24 +21,26 @@
     "unit-testing"
   ],
   "main": "dist/index.js",
-  "module": "lib/index.js",
+  "files": [
+    "dist/**/*"
+  ],
   "scripts": {
-    "build": "rollup -c && tsc",
     "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx}\"",
     "lint": "tslint \"./{types,src,pages}/**/*.ts?(x)\"",
     "test": "cross-env NODE_ENV=test jest --no-cache --config ./jest.config.js",
     "test:all": "npm-run-all format typecheck lint test:coverage",
     "test:coverage": "cross-env NODE_ENV=test jest --no-cache --coverage --config ./jest.config.js",
     "typecheck": "tsc"
   },
-  "prepublish": "build",
+  "prepublish": "tsc",
   "repository": {
     "type": "git",
     "url": "[email protected]:voodoocreation/react-test-wrapper.git"
   },
   "bugs": {
     "url": "https://github.com/voodoocreation/react-test-wrapper/issues"
   },
+  "homepage": "https://github.com/voodoocreation/react-test-wrapper#readme",
   "types": "dist/index.d.ts",
   "peerDependencies": {
     "enzyme": "^3.10.0",
@@ -77,9 +79,6 @@
     "react-intl": "^3.9.1",
     "react-redux": "^7.1.3",
     "redux": "^4.0.4",
-    "rollup": "^1.27.9",
-    "rollup-plugin-terser": "^5.1.2",
-    "rollup-plugin-typescript2": "^0.25.3",
     "ts-jest": "^24.2.0",
     "tslint": "^5.20.0",
     "tslint-config-prettier": "^1.18.0",

rollup.config.js

@@ -11,7 +11,7 @@ describe("Wrapper", () => {
     });
 
     describe("when using 'shallow'", () => {
-      const { wrapper } = component.shallow();
+      const wrapper = component.shallow();
 
       it("returns ShallowWrapper", () => {
         expect(wrapper).toBeInstanceOf(ShallowWrapper);
@@ -27,7 +27,7 @@ describe("Wrapper", () => {
     });
 
     describe("when using 'mount'", () => {
-      const { wrapper } = component.mount();
+      const wrapper = component.mount();
 
       it("returns ReactWrapper", () => {
         expect(wrapper).toBeInstanceOf(ReactWrapper);
@@ -43,7 +43,7 @@ describe("Wrapper", () => {
     });
 
     describe("when using 'render'", () => {
-      const { wrapper } = component.render();
+      const wrapper = component.render();
 
       it("returns Cheerio wrapper", () => {
         expect(wrapper.cheerio).toBe("[cheerio object]");
@@ -65,15 +65,15 @@ describe("Wrapper", () => {
     );
 
     it("renders default children correctly", () => {
-      const { wrapper } = component.render();
+      const wrapper = component.render();
 
       expect(wrapper.find(".Dummy--children").html()).toBe(
         "<div>Default children</div>"
       );
     });
 
     it("renders test-specific children correctly", () => {
-      const { wrapper } = component
+      const wrapper = component
         .withChildren(<span>Test children</span>)
         .render();
 
@@ -83,7 +83,7 @@ describe("Wrapper", () => {
     });
 
     it("clears test-specific children after previous test and renders default children again", () => {
-      const { wrapper } = component.render();
+      const wrapper = component.render();
 
       expect(wrapper.find(".Dummy--children").html()).toBe(
         "<div>Default children</div>"
@@ -97,24 +97,27 @@ describe("Wrapper", () => {
     });
 
     it("renders with default props correctly", () => {
-      const { wrapper } = component.render();
+      const wrapper = component.render();
 
+      expect(component.props).toEqual({ value: "Default value" });
       expect(wrapper.find(".Dummy--value").text()).toBe("Default value");
     });
 
     it("renders with test-specific props correctly", () => {
-      const { wrapper } = component
+      const wrapper = component
         .withProps({
           value: "Test value"
         })
         .render();
 
+      expect(component.props).toEqual({ value: "Test value" });
       expect(wrapper.find(".Dummy--value").text()).toBe("Test value");
     });
 
     it("clears test-specific props after previous test and uses default props again", () => {
-      const { wrapper } = component.render();
+      const wrapper = component.render();
 
+      expect(component.props).toEqual({ value: "Default value" });
       expect(wrapper.find(".Dummy--value").text()).toBe("Default value");
     });
   });