├── .circleci
└── config.yml
├── .eslintrc.json
├── .gitignore
├── .nvmrc
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── LICENSE
├── README.md
├── karma.conf.js
├── package.json
├── rollup.config.js
├── src
├── context.js
├── index.js
├── mount.js
├── setup-app.js
└── visit.js
├── tests
├── .eslintrc.json
├── index.js
├── mount-test.js
├── setup-app-test.js
└── visit-test.js
└── yarn.lock
/.circleci/config.yml:
--------------------------------------------------------------------------------
1 | references:
2 | defaults: &defaults
3 | working_directory: ~/react
4 | docker:
5 | - image: circleci/node:8-browsers
6 |
7 | cache_key: &cache_key
8 | react-v1-{{ .Branch }}-{{ checksum "yarn.lock" }}
9 |
10 | attach_workspace: &attach_workspace
11 | attach_workspace:
12 | at: ~/
13 |
14 | version: 2.0
15 | jobs:
16 | install:
17 | <<: *defaults
18 | steps:
19 | - checkout
20 | - restore_cache:
21 | name: Restore cache
22 | key: *cache_key
23 | - run:
24 | name: Install dependencies
25 | command: yarn
26 | - save_cache:
27 | name: Save cache
28 | key: *cache_key
29 | paths:
30 | - node_modules
31 | - persist_to_workspace:
32 | root: ~/
33 | paths:
34 | - react
35 | - .ssh
36 |
37 | lint:
38 | <<: *defaults
39 | steps:
40 | - *attach_workspace
41 | - run:
42 | name: Lint package
43 | command: yarn lint
44 |
45 | build:
46 | <<: *defaults
47 | steps:
48 | - *attach_workspace
49 | - run:
50 | name: Build documentation
51 | command: yarn docs
52 | - run:
53 | name: Build package
54 | command: yarn build
55 | - persist_to_workspace:
56 | root: ~/
57 | paths:
58 | - react/dist
59 | - react/docs
60 |
61 | test:
62 | <<: *defaults
63 | steps:
64 | - *attach_workspace
65 | - run:
66 | name: Run tests
67 | command: yarn test
68 |
69 | deploy:
70 | <<: *defaults
71 | steps:
72 | - *attach_workspace
73 | - run:
74 | name: Publish to NPM
75 | command: |
76 | echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc
77 | npx bigtest-release --access=public
78 | - run:
79 | name: Push Tags
80 | command: git push --tags
81 |
82 | workflows:
83 | version: 2
84 | default:
85 | jobs:
86 | - install
87 | - lint:
88 | requires:
89 | - install
90 | - build:
91 | requires:
92 | - install
93 | - test:
94 | requires:
95 | - install
96 | - deploy:
97 | requires:
98 | - lint
99 | - build
100 | - test
101 | filters:
102 | branches:
103 | only: master
104 |
--------------------------------------------------------------------------------
/.eslintrc.json:
--------------------------------------------------------------------------------
1 | {
2 | "parser": "babel-eslint",
3 | "extends": [
4 | "standard",
5 | "plugin:react/recommended"
6 | ],
7 | "rules": {
8 | "semi": ["error", "always"],
9 | "space-before-function-paren": ["error", {
10 | "anonymous": "never",
11 | "named": "never",
12 | "asyncArrow": "always"
13 | }],
14 | "indent": ["error", 2]
15 | }
16 | }
17 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | /node_modules
3 | /dist
4 | /docs
5 | *.log
6 |
--------------------------------------------------------------------------------
/.nvmrc:
--------------------------------------------------------------------------------
1 | 8
2 |
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 | All notable changes to this project will be documented in this file.
3 |
4 | The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
5 |
6 | ## [Unreleased]
7 |
8 | ## [0.1.2] - 2018-06-20
9 |
10 | ### Fixed
11 |
12 | - exception documentation
13 |
14 | ## [0.1.1] - 2018-05-30
15 |
16 | ### Fixed
17 |
18 | - README typos
19 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Contributor Covenant Code of Conduct
2 |
3 | ## Our Pledge
4 |
5 | In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
6 |
7 | ## Our Standards
8 |
9 | Examples of behavior that contributes to creating a positive environment include:
10 |
11 | * Using welcoming and inclusive language
12 | * Being respectful of differing viewpoints and experiences
13 | * Gracefully accepting constructive criticism
14 | * Focusing on what is best for the community
15 | * Showing empathy towards other community members
16 |
17 | Examples of unacceptable behavior by participants include:
18 |
19 | * The use of sexualized language or imagery and unwelcome sexual attention or advances
20 | * Trolling, insulting/derogatory comments, and personal or political attacks
21 | * Public or private harassment
22 | * Publishing others' private information, such as a physical or electronic address, without explicit permission
23 | * Other conduct which could reasonably be considered inappropriate in a professional setting
24 |
25 | ## Our Responsibilities
26 |
27 | Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
28 |
29 | Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
30 |
31 | ## Scope
32 |
33 | This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
34 |
35 | ## Enforcement
36 |
37 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at oss@frontside.io. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
38 |
39 | Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
40 |
41 | ## Attribution
42 |
43 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
44 |
45 | [homepage]: http://contributor-covenant.org
46 | [version]: http://contributor-covenant.org/version/1/4/
47 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2018 BigTest
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # :warning: DEPRECATED :warning:
2 | In order to make BigTest development faster and friction free, we've consolidated all of our individual projects into a [single repository on the Frontside Organization](https://github.com/thefrontside/bigtest). We'd love to see you there!
3 |
4 | _note: the last release from this repository was 0.1.2_
5 |
6 | ## @bigtest/react
7 |
8 | React DOM helpers for testing big
9 |
10 | ## What is this?
11 |
12 | This package aims to provide a set of helpers to make it easier to
13 | acceptance test your React applications.
14 |
15 | The `mount` helper will resolve after mounting a component in a
16 | freshly inserted DOM node. Subsequent uses will clean up any previously
17 | mounted component.
18 |
19 | ``` javascript
20 | import { mount } from '@bigtest/react';
21 | import Button from '../src/components/button';
22 |
23 | describe('My Button', () => {
24 | // `mount` returns a promise that resolves after rendering
25 | beforeEach(() => mount(() => ));
26 |
27 | it('renders', () => {
28 | expect(document.querySelector('.button')).to.exist;
29 | });
30 | });
31 | ```
32 |
33 | The `setupAppForTesting` helper not only mounts the application
34 | component, but will resolve with an instance of the component, and
35 | provide an in-memory history object for [React
36 | Router](https://github.com/ReactTraining/react-router) to use during
37 | testing.
38 |
39 | ``` javascript
40 | import { setupAppForTesting } from '@bigtest/react';
41 | import App from '../src/app';
42 |
43 | describe('My Application', () => {
44 | let app;
45 |
46 | beforeEach(async () => {
47 | app = await setupAppForTesting(App);
48 | });
49 |
50 | it('renders', () => {
51 | expect(document.querySelector('#app')).to.exist;
52 | });
53 |
54 | it('has a history prop', () => {
55 | // this prop is only provided if defined in `propTypes`
56 | expect(app.props).to.have.property('history');
57 | });
58 | });
59 | ```
60 |
61 | The `visit` helpers (`visit`, `goBack`, `goForward`, and `location`)
62 | only work after using `setupAppForTesting` and interface with the
63 | application's `history` prop to navigate between routes.
64 |
65 | ``` javascript
66 | import { setupAppForTesting, visit, location } from '@bigtest/react';
67 | import App from '../src/app';
68 |
69 | describe('My Application', () => {
70 | beforeEach(() => setupAppForTesting(App));
71 |
72 | describe('navigating', () => {
73 | beforeEach(() => visit('/some-route'));
74 |
75 | it('is at the new route', () => {
76 | expect(location()).to.have.property('pathname', '/some-route');
77 | });
78 | });
79 | });
80 | ```
81 |
82 | The `cleanup` helper is called at the start of every `mount` and
83 | `setupAppForTesting` call to clean up any previously mounted component
84 | or application. It can be also used on it's own if you need to clean
85 | up previously mounted components yourself.
86 |
87 | ``` javascript
88 | import { mount, cleanup } from '@bigtest/react';
89 | import Button from '../src/components/button';
90 |
91 | describe('My Button', () => {
92 | beforeEach(() => mount(() => ));
93 |
94 | // it's best not to do this so that you can investigate and play
95 | // with your component for debugging purposes after a test runs
96 | afterEach(() => cleanup());
97 |
98 | // ...
99 | });
100 | ```
101 |
102 | ### Options
103 |
104 | Both `mount` and `setupAppForTesting` accept a hash of `options` as
105 | the second argument.
106 |
107 | ``` javascript
108 | mount(Component, {
109 | // used as the ID of the newly inserted DOM node
110 | mountId: 'testing-root',
111 |
112 | // where to insert the new DOM node
113 | rootElement: document.body,
114 |
115 | // called before the component is mounted; if a promise is returned,
116 | // the component will mount after it resolves
117 | setup: () => {},
118 |
119 | // called during the next `cleanup` invocation, either at the
120 | // beginning of the next `mount` or `setupAppForTesting` call, or
121 | // when invoking `cleanup` directly; like `setup`, any returned
122 | // promise will cause it to wait until resolving
123 | teardown: () => {}
124 | })
125 | ```
126 |
127 | Additionally, `setupAppForTesting` accepts a `props` option which will
128 | pass along any user-defined props to the application component.
129 |
130 | ``` javascript
131 | setupAppForTesting(App, {
132 | props: {
133 | store: createStore(),
134 | // you can provide your own history object as well
135 | history: createHistory(historyOptions)
136 | }
137 | })
138 | ```
139 |
140 | ## Reusability
141 |
142 | For the most optimal experience when testing your application, any
143 | required application logic that does not live in a component's
144 | life-cycle hooks should be made reusable. Either by providing the
145 | necessary `setup` and `teardown` options, or by moving the logic into
146 | component life-cycle hooks.
147 |
148 | In addition to this, it will probably make sense to make use of
149 | `setupAppForTesting` inside of your own test helper where any other
150 | necessary setup is taken care of. This also allows us to not have to
151 | import our app and duplicate setup logic in every test file.
152 |
153 | ``` javascript
154 | // tests/helpers.js
155 | import { setupAppForTesting } from '@bigtest/react';
156 | export { visit, goBack, goForward, location } from '@bigtest/react';
157 |
158 | import App from '../src/app';
159 | import createServer from './mocks/server';
160 |
161 | export function setupApplicationForTesting() {
162 | beforeEach(async function () => {
163 | this.app = await setupAppForTesting(App, {
164 | setup: () => this.server = createServer(),
165 | teardown () => this.server.shutdown()
166 | });
167 | });
168 | }
169 | ```
170 |
171 | ## Even Better Testing
172 |
173 | While these helpers allow you to repeatedly mount your application for
174 | testing, interacting with your application can also be troublesome.
175 |
176 | [`@bigtest/interactor`](https://github.com/bigtestjs/interactor)
177 | provides an easy way to interact with the various parts of your app
178 | via any browser, just like a user would interact with your app. In
179 | fact, composable interactors are the perfect companion for testing
180 | an app made with composable components.
181 |
182 | ``` javascript
183 | import { setupAppForTesting } from '@bigtest/react';
184 |
185 | import App from '../src/app';
186 | import HomePageInteractor from './interactors/home';
187 |
188 | describe('My Application', () => {
189 | const home = new HomePageInteractor();
190 | beforeEach(() => setupAppForTesting(App))
191 |
192 | it('has a fancy button', () => {
193 | expect(home.button.isPresent).to.be.true;
194 | expect(home.button.isFancy).to.be.true;
195 | });
196 | });
197 | ```
198 |
199 | Check out the
200 | [`@bigtest/interactor`](https://github.com/bigtestjs/interactor) repo
201 | for more information about interactors and how they work.
202 |
--------------------------------------------------------------------------------
/karma.conf.js:
--------------------------------------------------------------------------------
1 | module.exports = (config) => {
2 | config.set({
3 | frameworks: ['mocha'],
4 | reporters: ['mocha'],
5 | browsers: ['Chrome'],
6 |
7 | files: [
8 | { pattern: 'tests/index.js', watched: false }
9 | ],
10 |
11 | preprocessors: {
12 | 'tests/index.js': ['webpack']
13 | },
14 |
15 | mochaReporter: {
16 | showDiff: true
17 | },
18 |
19 | webpack: {
20 | module: {
21 | rules: [{
22 | test: /\.js$/,
23 | exclude: /node_modules/,
24 | loader: 'babel-loader',
25 | options: {
26 | babelrc: false,
27 | presets: [
28 | ['@babel/env', {
29 | modules: false
30 | }],
31 | '@babel/stage-3',
32 | '@babel/react'
33 | ]
34 | }
35 | }]
36 | }
37 | },
38 |
39 | webpackMiddleware: {
40 | stats: 'minimal'
41 | },
42 |
43 | plugins: [
44 | 'karma-chrome-launcher',
45 | 'karma-mocha',
46 | 'karma-mocha-reporter',
47 | 'karma-webpack'
48 | ]
49 | });
50 | };
51 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "@bigtest/react",
3 | "description": "React DOM helpers for testing big",
4 | "version": "0.1.2",
5 | "license": "MIT",
6 | "repository": "https://github.com/bigtestjs/react",
7 | "main": "dist/umd/index.js",
8 | "module": "dist/esm/index.js",
9 | "files": [
10 | "dist",
11 | "docs",
12 | "src"
13 | ],
14 | "scripts": {
15 | "build": "rollup --config",
16 | "docs": "bigtest-docs",
17 | "lint": "eslint --ignore-path .gitignore ./",
18 | "postpublish": "bigtest-tag-version",
19 | "start": "karma start",
20 | "test": "karma start --single-run"
21 | },
22 | "peerDependencies": {
23 | "react": "^16.0.0",
24 | "react-dom": "^16.0.0"
25 | },
26 | "devDependencies": {
27 | "@babel/core": "^7.0.0-beta.0",
28 | "@babel/polyfill": "^7.0.0-beta.0",
29 | "@babel/preset-env": "^7.0.0-beta.0",
30 | "@babel/preset-react": "^7.0.0-beta.0",
31 | "@babel/preset-stage-3": "^7.0.0-beta.0",
32 | "@babel/register": "^7.0.0-beta.0",
33 | "@bigtest/meta": "bigtestjs/meta#v0.0.1",
34 | "babel-eslint": "^8.2.3",
35 | "babel-loader": "^8.0.0-beta.0",
36 | "chai": "^4.1.2",
37 | "chai-as-promised": "^7.1.1",
38 | "eslint": "^4.19.1",
39 | "eslint-config-standard": "^11.0.0",
40 | "eslint-plugin-import": "^2.12.0",
41 | "eslint-plugin-node": "^6.0.1",
42 | "eslint-plugin-promise": "^3.8.0",
43 | "eslint-plugin-react": "^7.8.2",
44 | "eslint-plugin-standard": "^3.1.0",
45 | "karma": "^2.0.2",
46 | "karma-chrome-launcher": "^2.2.0",
47 | "karma-mocha": "^1.3.0",
48 | "karma-mocha-reporter": "^2.2.5",
49 | "karma-webpack": "^3.0.0",
50 | "mocha": "^5.2.0",
51 | "prop-types": "^15.6.1",
52 | "react": "^16.0.0",
53 | "react-dom": "^16.0.0",
54 | "rollup": "^0.59.3",
55 | "rollup-plugin-babel": "^4.0.0-beta.0",
56 | "rollup-plugin-commonjs": "^9.1.3",
57 | "rollup-plugin-node-resolve": "^3.3.0",
58 | "webpack": "^3.10.0"
59 | },
60 | "dependencies": {
61 | "history": "^4.7.2"
62 | }
63 | }
64 |
--------------------------------------------------------------------------------
/rollup.config.js:
--------------------------------------------------------------------------------
1 | import babel from 'rollup-plugin-babel';
2 | import resolve from 'rollup-plugin-node-resolve';
3 | import commonjs from 'rollup-plugin-commonjs';
4 | import pkg from './package.json';
5 |
6 | export default {
7 | input: 'src/index.js',
8 | output: [{
9 | format: 'umd',
10 | name: 'BigTest.ReactHelpers',
11 | file: pkg.main,
12 | globals: {
13 | 'react': 'React',
14 | 'react-dom': 'ReactDOM'
15 | }
16 | }, {
17 | format: 'es',
18 | file: pkg.module
19 | }],
20 | external: [
21 | 'react',
22 | 'react-dom'
23 | ],
24 | plugins: [
25 | resolve(),
26 | commonjs({
27 | exclude: 'src/**'
28 | }),
29 | babel({
30 | babelrc: false,
31 | comments: false,
32 | presets: [
33 | ['@babel/env', {
34 | modules: false
35 | }],
36 | '@babel/stage-3',
37 | '@babel/react'
38 | ]
39 | })
40 | ]
41 | };
42 |
--------------------------------------------------------------------------------
/src/context.js:
--------------------------------------------------------------------------------
1 | // local context where various things can be persisted using the
2 | // helper functions below
3 | let context = Object.create(null);
4 |
5 | /**
6 | * Clears everything from the current context by creating a brand new
7 | * empty context.
8 | *
9 | * @private
10 | */
11 | export function clearContext() {
12 | context = Object.create(null);
13 | }
14 |
15 | /**
16 | * Adds things to the context by key, value.
17 | *
18 | * @private
19 | * @param {Object} newContexts - Hash of things to store in the
20 | * current context
21 | */
22 | export function setContext(newContext) {
23 | Object.assign(context, newContext);
24 | }
25 |
26 | /**
27 | * Retrieves the value of a specific key in the current context.
28 | *
29 | * @private
30 | * @param {String} key - The key of the value to retrieve
31 | * @param {String|Boolean} [error] - Specific error message to throw
32 | * @returns Value of `key` within the current context
33 | * @throws {Error} when `key` is not fonud in the current context
34 | */
35 | export function getContext(key, error) {
36 | if (typeof error === 'undefined') {
37 | error = `no ${key} context, make sure \`setupAppForTesting\` was called`;
38 | }
39 |
40 | if (key in context) {
41 | return context[key];
42 | } else if (error) {
43 | throw new Error(error);
44 | }
45 | }
46 |
--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
1 | export { default as mount, cleanup } from './mount';
2 | export { default as setupAppForTesting } from './setup-app';
3 | export { visit, goBack, goForward, location } from './visit';
4 |
--------------------------------------------------------------------------------
/src/mount.js:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 | import { render, unmountComponentAtNode } from 'react-dom';
3 | import { clearContext, setContext, getContext } from './context';
4 |
5 | /**
6 | * Creates a div with an ID and appends it into the `$root` element.
7 | *
8 | * @private
9 | * @param {String} id - Div ID
10 | * @param {Node} $root - Element to append the div into
11 | * @returns {Node} The appended div element
12 | */
13 | function insertNode(id, $root) {
14 | let $node = document.createElement('div');
15 | $node.id = id;
16 | $root.appendChild($node);
17 | return $node;
18 | }
19 |
20 | /**
21 | * Cleans up any component that was mounted by previously calling
22 | * `mount`, and clears the current context used by other helpers.
23 | *
24 | * The `teardown` option provided to the previous `mount` function
25 | * will be called when using this helper. If a promise is returned,
26 | * the cleanup will not happen until after that promise resovles.
27 | *
28 | * @function cleanup
29 | * @returns {Promise} Resolves after unmounting the component and
30 | * clearing the current context
31 | */
32 | export function cleanup() {
33 | let {
34 | node,
35 | teardown = () => {}
36 | } = getContext('mountOptions', false) || {};
37 |
38 | // maybe teardown
39 | return Promise.resolve().then(teardown)
40 | // unmount any existing node and clear the context
41 | .then(() => {
42 | if (node) {
43 | unmountComponentAtNode(node);
44 | node.parentNode.removeChild(node);
45 | }
46 |
47 | clearContext();
48 | });
49 | }
50 |
51 | /**
52 | * Mounts the component within a freshly inserted dom node. If there
53 | * was a component previously mounted by this function, the `cleanup`
54 | * helper is automatically used to safely unmount it and clear any
55 | * existing context.
56 | *
57 | * ``` javascript
58 | * await mount(() => (
59 | *
60 | *
61 | *
62 | * ))
63 | * ```
64 | *
65 | * The ID given to the mounting node can be customized by providing a
66 | * `mountId` option, and where the node is inserted into can be
67 | * controlled by providing a `rootElement`.
68 | *
69 | * The `setup` hook is called after cleaning up the previously mounted
70 | * component, and the new component is not mounted until after any
71 | * resulting promise resolves.
72 | *
73 | * The `teardown` hook is called on the next invokation of `cleanup`,
74 | * either by using it directly, or by calling `mount` again. Cleanup
75 | * will not complete until any optional promise returned from
76 | * `teardown` resolves.
77 | *
78 | * @function mount
79 | * @param {Component} component - The component to mount
80 | * @param {String} [options.mountId="testing-root"] - The ID given to
81 | * the insterted mounting node.
82 | * @param {Node} [options.rootElement=document.body] - The root
83 | * element the new node will be insterted into.
84 | * @param {Function} [options.setup] - Called after cleaning up the
85 | * previously mounted component but before mounting the new
86 | * component. If a promise is returned, the component will not be
87 | * mounted until after the promise resolves.
88 | * @param {Function} [options.teardown] - Called when `cleanup` is
89 | * used after mounting the component, or when `mount` is used
90 | * again. If a promise is returned, the component will not be
91 | * unmounted until after the promise resolves.
92 | * @returns {Promise} Resolves after the component has been mounted
93 | * into the newly inserted DOM node.
94 | */
95 | export default function mount(Component, options = {}) {
96 | let {
97 | mountId = 'testing-root',
98 | rootElement = document.body,
99 | setup = () => {},
100 | teardown
101 | } = options;
102 |
103 | // maybe clean & setup
104 | return cleanup().then(setup)
105 | // create a fresh mount node for the component
106 | .then(() => new Promise(resolve => {
107 | let node = insertNode(mountId, rootElement);
108 | setContext({ mountOptions: { node, teardown } });
109 | render(, node, resolve);
110 | }));
111 | }
112 |
--------------------------------------------------------------------------------
/src/setup-app.js:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 | import createHistory from 'history/createMemoryHistory';
3 |
4 | import { setContext, getContext } from './context';
5 | import mount from './mount';
6 |
7 | /**
8 | * Returns `true` or `false` if the component specifies a prop type in
9 | * it's static `propTypes`.
10 | *
11 | * @private
12 | * @param {Component} Component - Component class
13 | * @param {String} propType - Prop type name
14 | * @returns {Boolean} If the prop is accepted or not
15 | */
16 | function hasPropType(Component, propType) {
17 | return !!Component.propTypes && propType in Component.propTypes;
18 | }
19 |
20 | /**
21 | * Mounts an application component in the DOM with additional
22 | * properties useful for testing. Using the `props` option, you may
23 | * provide any custom properties to the app component.
24 | *
25 | * ``` javascript
26 | * setupAppForTesting(App, {
27 | * props: { testing: true },
28 | * setup: () => server = startMockServer(),
29 | * teardown: () => server.shutdown()
30 | * })
31 | * ```
32 | *
33 | * If the application component accepts a `history` property, and one
34 | * was not already provided via `props`, an in-memory history object
35 | * is created which can then be used with routers such as [React
36 | * Router]().
37 | *
38 | * The `history` object is kept in a context which is used by the
39 | * `visit` helpers to make it easy to navigate your app. The `visit`
40 | * helpers will not work unless `setupAppForTesting` is called at
41 | * least once.
42 | *
43 | * ``` javascript
44 | * // `history` must be defined as a prop type
45 | * App.propTypes = {
46 | * history: PropTypes.object
47 | * }
48 | *
49 | * // if this is not called, the visit helpers will throw errors
50 | * setupAppForTesting(App)
51 | *
52 | * // forwards to `history.push`
53 | * visit('/someroute')
54 | * visit({ pathname: '/foo', search: '?bar' })
55 | *
56 | * // other history helpers
57 | * goBack()
58 | * goForward()
59 | * ```
60 | *
61 | * Every time a new component is mounted via the `setupAppForTesting`
62 | * or `mount` helpers, or when using the `cleanup` helper, the
63 | * previous component is unmounted and the context is cleared.
64 | *
65 | * ``` javascript
66 | * setupAppForTesting(App)
67 | * visit('/someroute')
68 | * cleanup()
69 | *
70 | * visit('/someroute')
71 | * //=> Error: undefined history context
72 | * ```
73 | *
74 | * @function setupAppForTesting
75 | * @param {Component} App - The Application component class to mount
76 | * with additional properties
77 | * @param {Object} [options] - Mounting options passed along to `mount`
78 | * @param {Object} [options.props] - Additional props to pass to the
79 | * App component when it renders
80 | * @returns {Promise} Resolves with the app instance after it has been
81 | * mounted in the DOM
82 | */
83 | export default function setupAppForTesting(App, options = {}) {
84 | let { props = {}, ...mountOptions } = options;
85 |
86 | // ensure we don't mutate the incoming object
87 | props = Object.assign({}, props);
88 |
89 | // create an in-memory history object
90 | if (hasPropType(App, 'history') && !('history' in props)) {
91 | Object.assign(props, { history: createHistory() });
92 | }
93 |
94 | // save a reference to the app
95 | if (Object.getPrototypeOf(App) === React.Component) {
96 | Object.assign(props, { ref: app => setContext({ app }) });
97 | }
98 |
99 | // mount with props & options
100 | return mount(() => , mountOptions)
101 | .then(() => {
102 | // save the history context after mounting
103 | if ('history' in props) {
104 | setContext({ history: props.history });
105 | }
106 |
107 | // always resolve with the app if possible
108 | return getContext('app', false) || null;
109 | });
110 | }
111 |
--------------------------------------------------------------------------------
/src/visit.js:
--------------------------------------------------------------------------------
1 | import { getContext } from './context';
2 |
3 | /**
4 | * Uses the history context setup during `setupAppForTesting` and
5 | * calls `push` with the provided location argument.
6 | *
7 | * ``` javascript
8 | * // must be called to setup the `history` context
9 | * setupAppForTesting(App)
10 | *
11 | * // calls `history.push()`
12 | * visit('/someroute')
13 | * visit({ pathname: '/foo', search: '?bar' })
14 | * ```
15 | *
16 | * @function visit
17 | * @param {Object|String} location - Argument for `history.push()`
18 | * @throws {Error} When `setupAppForTesting` was not called
19 | */
20 | export function visit(location) {
21 | getContext('history').push(location);
22 | }
23 |
24 | /**
25 | * Uses the history context setup during `setupAppForTesting` and
26 | * calls the `goBack` method.
27 | *
28 | * ``` javascript
29 | * // must be called to setup the `history` context
30 | * setupAppForTesting(App)
31 | *
32 | * // go to a route
33 | * visit('/someroute')
34 | *
35 | * // go back
36 | * goBack()
37 | * ```
38 | *
39 | * @function goBack
40 | * @throws {Error} When `setupAppForTesting` was not called
41 | */
42 | export function goBack() {
43 | getContext('history').goBack();
44 | }
45 |
46 | /**
47 | * Uses the history context setup during `setupAppForTesting` and
48 | * calls the `goForward` method.
49 | *
50 | * ``` javascript
51 | * // must be called to setup the `history` context
52 | * setupAppForTesting(App)
53 | *
54 | * // go to a route, and back
55 | * visit('/someroute')
56 | * goBack()
57 | *
58 | * // go back to `/someroute`
59 | * goForward()
60 | * ```
61 | *
62 | * @function goForward
63 | * @throws {Error} When `setupAppForTesting` was not called
64 | */
65 | export function goForward() {
66 | getContext('history').goForward();
67 | }
68 |
69 | /**
70 | * Uses the history context setup during `setupAppForTesting`
71 | * and returns the current location.
72 | *
73 | * ``` javascript
74 | * // must be called to setup the `history` context
75 | * setupAppForTesting(App)
76 | * visit('/someroute')
77 | *
78 | * location().pathname
79 | * //=> "/someroute"
80 | * ```
81 | *
82 | * @returns {Object} Current history location object
83 | * @throws {Error} When `setupAppForTesting` was not called
84 | */
85 | export function location() {
86 | return getContext('history').location;
87 | }
88 |
--------------------------------------------------------------------------------
/tests/.eslintrc.json:
--------------------------------------------------------------------------------
1 | {
2 | "rules": {
3 | "no-return-assign": 0,
4 | "no-unused-expressions": 0
5 | }
6 | }
7 |
--------------------------------------------------------------------------------
/tests/index.js:
--------------------------------------------------------------------------------
1 | require('@babel/polyfill');
2 | const chai = require('chai');
3 | const chaiAsPromised = require('chai-as-promised');
4 |
5 | chai.use(chaiAsPromised);
6 |
7 | const requireTest = require.context('.', true, /-test/);
8 | requireTest.keys().forEach(requireTest);
9 |
--------------------------------------------------------------------------------
/tests/mount-test.js:
--------------------------------------------------------------------------------
1 | /* global describe, beforeEach, afterEach, it */
2 | import React from 'react';
3 | import { expect } from 'chai';
4 | import mount, { cleanup } from '../src/mount';
5 |
6 | describe('BigTest React Helpers: mount', () => {
7 | let mounted = false;
8 |
9 | class Test extends React.Component {
10 | componentDidMount() {
11 | mounted = true;
12 | }
13 |
14 | componentWillUnmount() {
15 | mounted = false;
16 | }
17 |
18 | render() {
19 | return ;
20 | }
21 | }
22 |
23 | it('mounts the component', async () => {
24 | expect(mounted).to.be.false;
25 | expect(document.getElementById('test')).to.not.exist;
26 |
27 | await expect(mount(() => )).to.be.fulfilled;
28 |
29 | expect(document.getElementById('test')).to.exist;
30 | expect(mounted).to.be.true;
31 | });
32 |
33 | it('mounts the component in a new DOM node', async () => {
34 | let $mount1, $mount2;
35 |
36 | await expect(mount(() => )).to.be.fulfilled;
37 | $mount1 = document.getElementById('testing-root');
38 |
39 | expect($mount1.parentNode).to.equal(document.body);
40 |
41 | await expect(mount(() => )).to.be.fulfilled;
42 | $mount2 = document.getElementById('testing-root');
43 |
44 | expect($mount2.parentNode).to.equal(document.body);
45 | expect($mount1.parentNode).to.be.null;
46 | expect($mount1).to.not.equal($mount2);
47 | });
48 |
49 | it('cleans up previously mounted components', async () => {
50 | await expect(mount(() => )).to.be.fulfilled;
51 | await expect(mount(() => )).to.be.fulfilled;
52 |
53 | expect(document.getElementById('test1')).to.not.exist;
54 | expect(document.getElementById('test2')).to.exist;
55 | });
56 |
57 | describe('calling cleanup', () => {
58 | it('cleans up the mounted component', async () => {
59 | await expect(mount(() => )).to.be.fulfilled;
60 | expect(document.getElementById('test')).to.exist;
61 | expect(mounted).to.be.true;
62 |
63 | await expect(cleanup()).to.be.fulfilled;
64 | expect(document.getElementById('test')).to.not.exist;
65 | expect(mounted).to.be.false;
66 | });
67 | });
68 |
69 | describe('specifying a different mountId', () => {
70 | it('mounts the component in a new DOM node with a different ID', async () => {
71 | expect(document.getElementById('test')).to.not.exist;
72 | await expect(mount(() => , { mountId: 'test' })).to.be.fulfilled;
73 | expect(document.getElementById('test')).to.exist;
74 | });
75 |
76 | it('cleans up the previously mounted component', async () => {
77 | await expect(mount(() => , { mountId: 'test1' })).to.be.fulfilled;
78 | expect(document.getElementById('test1')).to.exist;
79 |
80 | await expect(mount(() => , { mountId: 'test2' })).to.be.fulfilled;
81 | expect(document.getElementById('test1')).to.not.exist;
82 | expect(document.getElementById('test2')).to.exist;
83 | });
84 | });
85 |
86 | describe('specifying a different rootElement', () => {
87 | let $root;
88 |
89 | beforeEach(() => {
90 | $root = document.createElement('div');
91 | document.body.appendChild($root);
92 | });
93 |
94 | afterEach(() => {
95 | document.body.removeChild($root);
96 | $root = null;
97 | });
98 |
99 | it('inserts the mounting node into a different rootElement', async () => {
100 | await expect(mount(() => , { rootElement: $root })).to.be.fulfilled;
101 | expect(document.getElementById('testing-root').parentNode).to.equal($root);
102 | });
103 |
104 | it('cleans up the previous rootElement', async () => {
105 | let $mount1, $mount2;
106 |
107 | await expect(mount(() => , { rootElement: $root })).to.be.fulfilled;
108 | $mount1 = document.getElementById('testing-root');
109 | expect($mount1.parentNode).to.equal($root);
110 |
111 | await expect(mount(() => )).to.be.fulfilled;
112 | $mount2 = document.getElementById('testing-root');
113 | expect($mount2.parentNode).to.equal(document.body);
114 | expect($mount1.parentNode).to.be.null;
115 | });
116 | });
117 |
118 | describe('with setup and teardown functions', () => {
119 | it('calls setup before mounting the component', async () => {
120 | let called = false;
121 |
122 | await expect(mount(() => , {
123 | setup() {
124 | expect(document.getElementById('test')).to.not.exist;
125 | called = true;
126 | }
127 | })).to.be.fulfilled;
128 |
129 | expect(document.getElementById('test')).to.exist;
130 | expect(called).to.be.true;
131 | });
132 |
133 | it('waits for any returned promise to resolve from setup', async () => {
134 | let called = false;
135 |
136 | await expect(mount(() => , {
137 | setup: () => new Promise(resolve => {
138 | expect(document.getElementById('test')).to.not.exist;
139 | called = true;
140 | resolve();
141 | })
142 | })).to.be.fulfilled;
143 |
144 | expect(document.getElementById('test')).to.exist;
145 | expect(called).to.be.true;
146 | });
147 |
148 | it('rejects and does not mount the component if setup errors', async () => {
149 | await expect(mount(() => , {
150 | setup() { throw new Error('err'); }
151 | })).to.be.rejectedWith('err');
152 |
153 | expect(document.getElementById('test')).to.not.exist;
154 | });
155 |
156 | it('calls the previous teardown function before the next setup function', async () => {
157 | let setup = false;
158 | let teardown = false;
159 |
160 | await expect(mount(() => , {
161 | teardown() {
162 | expect(setup).to.be.false;
163 | teardown = true;
164 | }
165 | })).to.be.fulfilled;
166 |
167 | await expect(mount(() => , {
168 | setup() {
169 | expect(teardown).to.be.true;
170 | setup = true;
171 | }
172 | })).to.be.fulfilled;
173 |
174 | expect(setup).to.be.true;
175 | expect(teardown).to.be.true;
176 | });
177 |
178 | describe('calling cleanup', () => {
179 | it('calls teardown from the previous mount options', async () => {
180 | let setup = false;
181 | let teardown = false;
182 |
183 | await expect(mount(() => , {
184 | setup() { setup = true; },
185 | teardown() { teardown = true; }
186 | })).to.be.fulfilled;
187 |
188 | expect(setup).to.be.true;
189 | expect(teardown).to.be.false;
190 |
191 | await expect(cleanup()).to.be.fulfilled;
192 |
193 | expect(setup).to.be.true;
194 | expect(teardown).to.be.true;
195 | });
196 | });
197 | });
198 | });
199 |
--------------------------------------------------------------------------------
/tests/setup-app-test.js:
--------------------------------------------------------------------------------
1 | /* global describe, beforeEach, it */
2 | import React from 'react';
3 | import PropTypes from 'prop-types';
4 | import { expect } from 'chai';
5 |
6 | import setupAppForTesting from '../src/setup-app';
7 | import { cleanup } from '../src/mount';
8 |
9 | describe('BigTest React Helpers: setupAppForTesting', () => {
10 | let App;
11 |
12 | beforeEach(() => {
13 | App = class App extends React.Component {
14 | render() { return ; }
15 | };
16 | });
17 |
18 | it('mounts the app', async () => {
19 | await expect(setupAppForTesting(App)).to.be.fulfilled;
20 | expect(document.getElementById('app')).to.exist;
21 | });
22 |
23 | it('resolves with the app', async () => {
24 | await expect(setupAppForTesting(App))
25 | .to.eventually.be.an.instanceOf(App);
26 | });
27 |
28 | it('forwards additional props', async () => {
29 | let app = await setupAppForTesting(App, {
30 | props: { test: true }
31 | });
32 |
33 | expect(app.props).to.have.property('test', true);
34 | });
35 |
36 | it('accepts mount options', async () => {
37 | let $root = document.createElement('div');
38 | let setup, teardown;
39 |
40 | await setupAppForTesting(App, {
41 | mountId: 'test-app',
42 | rootElement: $root,
43 | setup: () => setup = true,
44 | teardown: () => teardown = true
45 | });
46 |
47 | expect(setup).to.be.true;
48 | expect(teardown).to.be.undefined;
49 | expect($root.firstChild).to.have.property('id', 'test-app');
50 | expect($root.querySelector('#app')).to.exist;
51 |
52 | // cleanup triggers the previous teardown
53 | await cleanup();
54 | expect(teardown).to.be.true;
55 | });
56 |
57 | describe('with a history prop type', () => {
58 | beforeEach(() => {
59 | App.propTypes = {
60 | history: PropTypes.object
61 | };
62 | });
63 |
64 | it('receives a history object', async () => {
65 | let app = await setupAppForTesting(App);
66 |
67 | expect(app.props).to.have.property('history')
68 | .that.contains.keys(['push', 'goBack', 'goForward', 'location']);
69 | });
70 |
71 | it('allows a custom history object', async () => {
72 | let history = { fake: true };
73 | let app = await setupAppForTesting(App, {
74 | props: { history }
75 | });
76 |
77 | expect(app.props)
78 | .to.have.property('history')
79 | .that.equals(history);
80 | });
81 | });
82 |
83 | describe('with a stateless functional component', () => {
84 | beforeEach(() => {
85 | // eslint-disable-next-line react/display-name
86 | App = () => ;
87 | });
88 |
89 | it('mounts the app', async () => {
90 | await expect(setupAppForTesting(App)).to.be.fulfilled;
91 | expect(document.getElementById('app')).to.exist;
92 | });
93 |
94 | it('resolves with null', async () => {
95 | await expect(setupAppForTesting(App)).to.eventually.be.null;
96 | });
97 | });
98 | });
99 |
--------------------------------------------------------------------------------
/tests/visit-test.js:
--------------------------------------------------------------------------------
1 | /* global describe, beforeEach, it */
2 | import React from 'react';
3 | import PropTypes from 'prop-types';
4 | import { expect } from 'chai';
5 |
6 | import setupAppForTesting from '../src/setup-app';
7 | import { visit, goBack, goForward, location } from '../src/visit';
8 | import { cleanup } from '../src/mount';
9 |
10 | class App extends React.Component {
11 | static propTypes = {
12 | history: PropTypes.object
13 | };
14 |
15 | componentDidMount() {
16 | // re-render when the location changes
17 | this._unlisten = this.props.history.listen(() => {
18 | this.forceUpdate();
19 | });
20 | }
21 |
22 | componentWillUnmount() {
23 | this._unlisten();
24 | }
25 |
26 | // easy access to the current location
27 | get location() {
28 | return this.props.history.location;
29 | }
30 |
31 | render() {
32 | return (
33 |
34 | {this.location.pathname}
35 |
36 | );
37 | }
38 | };
39 |
40 | describe('BigTest React Helpers: visit helpers', () => {
41 | it('throws an error when used before `setupAppForTesting`', () => {
42 | let err = 'no history context, make sure `setupAppForTesting` was called';
43 |
44 | expect(() => visit('/blah')).to.throw(err);
45 | expect(() => goBack()).to.throw(err);
46 | expect(() => goForward()).to.throw(err);
47 | expect(() => location()).to.throw(err);
48 | });
49 |
50 | describe('after calling `setupAppForTesting`', () => {
51 | let app, $app;
52 |
53 | beforeEach(async () => {
54 | app = await setupAppForTesting(App);
55 | $app = document.getElementById('app');
56 | });
57 |
58 | it('can visit a location', () => {
59 | visit('/visit');
60 | expect(app.location).to.have.property('pathname', '/visit');
61 | expect($app.textContent).to.equal('/visit');
62 | });
63 |
64 | it('can go back', () => {
65 | visit('/back');
66 | expect(app.location).to.have.property('pathname', '/back');
67 | expect($app.textContent).to.equal('/back');
68 |
69 | goBack();
70 | expect(app.location).to.have.property('pathname', '/');
71 | expect($app.textContent).to.equal('/');
72 | });
73 |
74 | it('can go forward', () => {
75 | visit('/forward');
76 | goBack();
77 |
78 | expect(app.location).to.have.property('pathname', '/');
79 | expect($app.textContent).to.equal('/');
80 |
81 | goForward();
82 | expect(app.location).to.have.property('pathname', '/forward');
83 | expect($app.textContent).to.equal('/forward');
84 | });
85 |
86 | it('can get the current location', () => {
87 | visit('/test');
88 |
89 | let loc = location();
90 | expect(loc).to.equal(app.location);
91 |
92 | goBack();
93 | expect(location()).to.not.equal(loc);
94 | expect(location()).to.equal(app.location);
95 | });
96 | });
97 |
98 | describe('after cleanup', () => {
99 | beforeEach(async () => {
100 | await setupAppForTesting(App);
101 | await cleanup();
102 | });
103 |
104 | it('throws an error again', () => {
105 | let err = 'no history context, make sure `setupAppForTesting` was called';
106 |
107 | expect(() => visit('/blah')).to.throw(err);
108 | expect(() => goBack()).to.throw(err);
109 | expect(() => goForward()).to.throw(err);
110 | expect(() => location()).to.throw(err);
111 | });
112 | });
113 | });
114 |
--------------------------------------------------------------------------------