ES-Feature-Tests

by getify

Feature Tests for JavaScript

201 Stars 19 Forks Last release: Not found 32 Commits 16 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

ES Feature Tests

Feature Tests for JavaScript. This is the library used by the FeatureTests.io service.

If you're looking for the repository for the site itself, not this library, go here instead.

Why

Load the library, request feature test results for the current browser, use those results to determine what code to deliver for your application!

If all the JavaScript features/syntax your code uses are supported natively by the browser, why would you load up the ugly transpiled code? Why would you load dozens of kb of polyfills/shims if all (or most of) those APIs are already built-in?

Just use the original authored ES6+ code in newest browsers! Only use transpiled code and polyfills/shims for browsers which are missing the features/syntax you need.

Don't rely on stale caniuse data baked into build tools that matches a browser based on brittle UserAgent string parsing. Feature Test! That's the most reliable and sensible approach.

For much more detail about the why motivations and sanity checking the risks/concerns about scalability/reliability, see ES6: Features By Testing.

Documentation

The updated and detailed documentation for how this library works and what test results are available can be found on FeatureTests.io/details.

Hosting vs. Hosted

Hosting this package locally on your server is mostly useful if you want to use the feature tests in your Node/iojs programs (see "Node/iojs" below).

You can install this package locally and web host your own copy of the library files if you prefer. You'll need to modify the URLs ("https://featuretests.io") in several places to get them to load correctly. Hosting the files also means the test results won't be shareable with other sites, which puts more testing burden on users' machines.

Another concern that only applies if you're self-hosting and running your own tests is that all of the syntax-realted tests require using

new Function(..)
(or, ugh,
eval(..)
). If your site has a restrictive CSP, you will not be able to run those tests unless you relax it to allow
unsafe-eval
. By allowing the service to run the tests, that CSP policy is contained to the "featuretests.io" domain instead of polluting your site's domain.

It's probably a much better idea to use the "https://featuretests.io" service's hosted versions of the files for web usage.

Web

Using this library on the web:


Node/iojs

Using this library in Node/iojs:

npm install es-feature-tests

Then:

var ReflectSupports = require("es-feature-tests");

ReflectSupports( "all", function(results,timestamp){ console.log( results ); // { // .. // } });

Testify CLI

This package also includes a

testify
CLI tool, which scans files for ES6 features and produces the code for a JS function called
checkFeatureTests(..)
. For example:
function checkFeatureTests(testResults){return testResults.letConst&&testResults.templateString}

As shown,

checkFeatureTests(..)
receives the feature test results (as provided by this es-feature-tests library), and returns
true
or
false
indicating if the test results are sufficient or not. This test tells you if your ES6-authored files can be loaded directly into the environment in question, or if you need to load the transpiled version of your code.

In the preceding example, both the

letConst
test result and the
templateString
test result must pass for
checkFeatureTests(..)
to pass.

By letting

testify
scan your files, you won't need to manually maintain a list of checks for your code base. Just simply run
testify
during your build process, and include the code it produces (like shown above) into your initial bootstrapped code that will run the feature tests. Use the generated
checkFeatureTests(..)
with the es-feature-tests library like so:
var supports = window["Reflect.supports"];

// or in Node: // var supports = require("es-feature-tests");

supports( "all", function(results){ if (checkFeatureTests(results)) { // load ES6 code } else { // load transpiled code instead } });

The

testify
CLI tool has the following options:
usage: testify [--file|--dir]=path [opt ...]

options: --help show this help

--file=file scan a single file --dir=directory scan all files in a directory --exclude=pattern exclude any included paths that match pattern (JS regex) -C, --input scan file contents from STDIN

--output=[simple|json|babel|traceur] control output format (see docs) (default: simple) --enable=test-name force inclusion of a test by name --disable=test-name force exclusion of a test by name

-R, --recursive directory scan is recursive (default: off) -M, --ignore-missing ignore missing dependency files (default: off) -I, --ignore-invalid ignore JS parsing issues (default: off)

Specify file(s) to scan by using one or more

--file
and/or
--dir
flags, and/or import text contents via
STDIN
by specifying
--input (-C)
.

If you use

--dir
, that directory's contents will be examined (non-recursively), and all found JS files will be scanned. Use
--recursive (-R)
to recursively examine sub-directories. To exclude any files/paths from this processing, use one or more
--exclude
flags, specifying a JS-style regular expression to match for exclusion (note: to avoid shell escaping issues, surround your regex in ' ' quotes).

The default (

--output=simple
) output of the
testify
CLI tool is the code for the
checkFeatureTests(..)
function, as described above. If you'd prefer to receive a JSON string holding the array of tests needed by name, specify
--output=json
. If you want to produce a Babel config with tests needed mapped to the
whitelist
option
, use
--output=babel
. To produce the configuration for Traceur, use
--output=traceur
.

To force the inclusion of a specific test check, use

--enable
and specify the name (matching the test result name from this es-feature-tests library). To exclude a specific test check, use
--disable
and specify the matching name.

Suppress errors for missing scan files with

--ignore-missing
and for invalid files (failure to parse the JS) with
--ignore-invalid
.

Testify Library

testify
can also be used programmatically in JS:
var testify = require("es-feature-tests/testify"),
    code = testify.scan({ ..options.. });

// (Optional) To use the function inside Node: var checkFeatureTests = new Function( "res", code + ";return checkFeatureTests(res)" );

The options correspond similarly to the CLI parameters described above:

  • files
    (
    string
    ,
    array
    ): specifies file(s) to scan
  • dirs
    (
    string
    ,
    array
    ): specifies director(ies) of file(s) to scan
  • excludes
    (
    string
    ,
    array
    ): specifies exclusion pattern(s)
  • content
    (
    string
    ): specifies text to scan as if it was already read from a file
  • output
    (
    string
    :
    "simple"
    ,
    "json"
    ,
    "babel"
    ,
    "traceur"
    ): controls the output formatting of the list of tests needed

Note: The CLI

--output
option defaults to
"simple"
(the code for
checkFeatureTests(..)
), but the default value for the library option is
"json"
, which *actually produces the array object itself, since that will likely be more useful when used programmatically. *
enabled
(
string
,
array
): specifies test(s) that should always be included *
disabled
(
string
,
array
): specifies test(s) that should never be included *
recursive
(
boolean
, default:
false
): make directory scans recursive *
ignore
(
object
,
boolean
): if
true
/
false
, will set all sub-properties accordingly; otherwise, should be an object with one or more of these: -
ignore.missing
(
boolean
): ignore files or directories not found -
ignore.invalid
(
boolean
): ignore files where the scan fails

Note:

files
,
dirs
, and
excludes
all have the -
s
suffix, and
enabled
and
disabled
both have the -
d
suffix. However, the associated CLI parameter names do not have these suffixes.

GitHub

If you install this package from GitHub instead of npm, you won't have the

deploy/*
files for deployment. Run these commands from the main repo directory to build them:
npm install
npm run build

License

The code and all the documentation are all (c) 2015 Kyle Simpson and released under the MIT license.

http://getify.mit-license.org/

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.