Factable

A test case generation and managment tool for nodejs babel transpiled projects.

Contents

• What is Factable?
• Why?
• How does it work?
• Quick start
• Factable UI usage
• Try Factable with Factable Test Project
• Facts about Factable

What is Factable?

Factable intercepts your runtime function calls, lets you visualize and define your relevant test cases and then writes tests for them.

Even if you dont't care about test generation, Factable is a great tool to be aware of what's really happening with your functions.

Why?

Have you ever found yourself running your app and logging your function call inputs and outputs just to use them for your test mocks and assertions?

Have you ever wanted a way to register your runtime function calls to help you build your tests?

We are lazy. Every time we find ourselves doing stuff that could be automated or at least assisted, we go for it. Thats why Factable exists.

How does it work?

First, your function body is wrapped (at transpiling time) through a babel plugin that registers all relevant runtime information.

Then, that information is sent to a local server which serves it to the browser, where the client UI resides.

Lastly, UI client connects to the server through http and websockets to manage user interaction.

Factable Server can register function calls and write and delete test files.

Factable saves its state in "factable.json" file in the root of your project. Every test metadata is saved there. You should include it in your git tracked files.

---

Quick start

1. Install factable as dev dependency:

npm install -D factable

1. Add factable babel plugin to your current babel config:

   .babelrc:

   {
       "presets": [
           [
               "@babel/preset-env"
           ]
       ],
       "plugins": [
           "module:factable" // new
       ]
   }
   

   Notice "module:" prefix is required

   or to babel.config.js:

    const factablePlugin = require("factable"); // new
   
    module.exports = function (api) {
        api.cache(true);
        const presets = ["@babel/preset-env"];
        const plugins = [factablePlugin]; // new
    
        return {
            presets,
            plugins,
        };
    };
    

2. Add Factable to your scripts:

   Remember Factable is just a dev-tool and should only be used in your development process.

   Please don't use it in your production builds!

   • Set env variable FACTABLE_TRANSPILE={PORT} in every development (babel related) build script:

   package.json

   "scripts": {
   
       "dev": "babel-node ./src",
       "dev:factable": "cross-env FACTABLE_TRANSPILE=8888 babel-node ./src", // new
   
   },
   

   or:

   "scripts": {
   
       "build": "babel -d ./build ./src",
       "build:factable": "cross-env FACTABLE_TRANSPILE=8888 babel -d ./build ./src", // new
   
   },
   

   FACTABLE_TRANSPILE=8888 tells factable to transpile and set Factable Server port to 8888.

   • Add a script to start Factable Server:

   package.json

   "scripts": {
   
       "factable": "factable-server-run 8888",
   
   },
   

   factable-server-run 8888 is the cli command that launches Factable Server on port 8888 Make sure to put the same port value in both build and Factable Server scripts.

3. Add factable comment at the top of any file where you want Factable to intercept function calls:

// FACTABLE

export const someFancyFunc = ({ foo, bar, dontshowthis }, second = "hello") => (baz) => {
  return `${dontshowthis ? "" : foo + bar}${second}${baz}`;
};

1. Start Factable Server:

   npm run factable
   

   This will launch a browser window with the UI.

2. Run your app with Factable flag:

   npm run dev:factable
   

3. Play with Factable Server UI and find your function and its calls. Please, refer to Factable UI usage for more information.

---

Try Factable with Factable Test Project

You can also try Factable just cloning Factable Test Project and following its instructions.

---

Facts about Factable

• Factable helps you understand your functions better.
• Factable pretends to help you build tests as soon as possible.
• Factable likes and promotes TDD and BDD.
• Factable loves Funcional Programming (pure functions, inmutability) and aims to be a tool that promotes its best practices and increases awareness about its benefits.
• Factable tests are not perfect and will not always pass: It's up to you to make them work and pass! There are many cases (examples later) where factable can't build your function call, but it is still very usefull as it takes care of all the boilerplate. For now, you can freely manually edit and fix test files, just remember not to 'Edit' or 'Discard' it from Factable UI
• Factable is intended to be used with Git: we write, update, and also eventually delete test files, so we rely on git for recovering any previous file state.
• Factable only captures function calls server-side. Client-side is still a work in progress.
• Remember Factable is just a dev-tool and should only be used in your development process. Please don't use it in your production builds!