Build and Unit Testing

Clone a clean copy of the UserALE.js Repo, switch to the appropriate branch under test (e.g., release candidate)

$ git clone https://gitbox.apache.org/repos/asf/incubator-flagon-useralejs.git
$ git checkout [branch for test, e.g., vX.Y.Z-RC#]


cd in `incubator-flagon-useralejs`

$ npm install

This command will reference UserALE.js `package.json` file to install dev dependencies. Check for deprecation notices and for vulnerabilities, reported by npm at the completion of this step. Releases may tolerate deprecation notices and vulnerabilities, but it's up to the community to decide what this tolerance is through voting.


npm also allows for auditing vulnerabilities:

$ npm audit

This will reference the specific vulnerability, describe it (with more detail via linked information), and report which depth 1 dependencies (direct dev dependencies listed in package.json) are ultimately responsible for the vulnerability.

>TODO ADD EXAMPE IMG<

NOTE: at this point it is wise to run integration tests on userale.js artifacts included in the distribution. This will help eliminate issues with pre-built scripts, which may be missed if you run build scripts, replacing pre-built artifacts.

Once you're satisfied with the performance of pre-built scripts, test the build process and newly built artifacts. 


Follow standard build instructions, as per: https://github.com/apache/incubator-flagon-useralejs/blob/master/README.md

$ npm run build

This will run build scripts, resulting in fresh userale-X.Y.Z.js and userale-X.Y.Z.min.js scripts, as well as a fresh UserAleWebExtension/ build. To test more rigorously, delete the existing userale scripts and the contents of UserAleWebExtension to see if builds produce: 1. correctly versioned userale scripts, 2. complete build artifacts.

Terminal output from the build process should look like this:

> flagon-userale@2.0.2 build /Users/jpoore/Documents/Apache_Flagon/test/node_modules/flagon-userale
> gulp build

[23:02:50] Using gulpfile ~/Documents/Apache_Flagon/test/node_modules/flagon-userale/gulpfile.js
[23:02:50] Starting 'build'...
[23:02:50] Starting 'rollup'...
[23:02:51] Finished 'rollup' after 209 ms
[23:02:51] Starting 'build-web-ext'...
[23:02:51] Starting 'rollup-web-ext-content'...
[23:02:51] Finished 'rollup-web-ext-content' after 111 ms
[23:02:51] Starting 'rollup-web-ext-background'...
[23:02:51] Finished 'rollup-web-ext-background' after 59 ms
[23:02:51] Starting 'rollup-web-ext-options'...
[23:02:51] Finished 'rollup-web-ext-options' after 14 ms
[23:02:51] Starting '<anonymous>'...
[23:02:51] Finished '<anonymous>' after 29 ms
[23:02:51] Finished 'build-web-ext' after 214 ms
[23:02:51] Starting '<anonymous>'...
[23:02:51] Finished '<anonymous>' after 282 ms
[23:02:51] Finished 'build' after 709 ms

Next, run unit tests:

$ npm run test

In order to proceed with releases, unit tests must NOT FAIL. The output of unit tests should look like this:

attachHandlers
✓ attaches all the event handlers without duplicates
✓ debounces bufferedEvents (504ms)
defineDetails
- configures high detail events correctly

configure
✓ merges new configs into main config object
✓ includes a userid if present in the window.location
getUserIdFromParams
✓ fetches userId from URL params
✓ returns null if no matching param

getInitialSettings
timeStampScale
✓ no event.timestamp
✓ zero
✓ epoch milliseconds
✓ epoch microseconds
✓ performance navigation time
getInitialSettings
✓ fetches all settings from a script tag (84ms)
✓ grabs user id from params

Userale API
✓ provides configs
✓ edits configs
✓ starts + stops (213ms)
✓ sends custom logs

packageLogs
setLogFilter
✓ assigns the handler to the provided value
✓ allows the handler to be nulled
setLogMapper
✓ assigns the handler to the provided value
✓ allows the handler to be nulled
packageLog
✓ only executes if on
✓ calls detailFcn with the event as an argument if provided
✓ packages logs
✓ filters logs when a handler is assigned and returns false
✓ assigns logs to the mapper's return value if a handler is assigned
✓ does not call the map handler if the log is filtered out
✓ does not attempt to call a non-function filter/mapper
extractTimeFields
✓ returns the millisecond and microsecond portions of a timestamp
✓ sets micro to 0 when no decimal is present
✓ always returns an object
getLocation
✓ returns event page location
✓ calculates page location if unavailable
✓ fails to null
selectorizePath
✓ returns a new array of the same length provided
getSelector
✓ builds a selector
✓ identifies window
✓ handles a non-null unknown value
buildPath
✓ builds a path
✓ defaults to path if available

sendLogs
✓ sends logs on an interval
✓ does not send logs if the config is off
✓ sends logs on page exit with navigator
✓ sends logs on page exit without navigator
✓ does not send logs on page exit if config is off


45 passing (911ms)
1 pending


Integration Testing for UserALE.js


Integration tests provide an end-to-end test of logging functionality from application to logging server. The UserALE.js Example Webpage and Server provide a convenient mechanism to test critical build artifacts (e.g., userale scripts) in this pipeline. The example website also provides API usage examples that can be used to test whether the API is intact in distributed or built artifacts. Documentation on the Example Test Utilities can be found here: https://github.com/apache/incubator-flagon-useralejs/tree/v2.0.2-RC1/example.  

Testing the UserALE.js npm package (flagon-userale)


Clone a clean copy of the UserALE.js Repo, switch to the appropriate branch under test (e.g., release candidate)

$ git clone https://gitbox.apache.org/repos/asf/incubator-flagon-useralejs.git
$ git checkout [branch for test, e.g., vX.Y.Z-RC#]


In the parent directory of your cloned repo use `npm pack` to build a tarball that emulates the same process that npm will publish the package to the npm registry: 

$ npm pack ./incubator-flagon-useralejs

This builds a tarball in the parent repo: flagon-userale-X.Y.Z.tgz

Next install this tarball as one would install any package from npm

$ npm install flagon-userale-X.Y.Z.tgz

You'll note a few error messages, which indicate that no package.json file was found in the dir that you ran npm install–this is expected.

You'll find a new package-lock.json file in the dir (ignore this), and a `node_modules` file. Navigate to the `node_modules` file.

You will find the `flagon-userale` package in node_modules, exactly as you would if you installed it directly from the npm registry.

To test, cd into `flagon-userale`: 

$ npm install

This command will reference UserALE.js `package.json` file to install dev dependencies.

Following this, you can proceed with running build tests, unit tests, and integration tests as described above.

Auditing Release Packages

Using RAT to Verify Apache Licensing

The Release Auditing Tool is tailor-made to evaluate license headers on the file structure of a release, and it's very accurate. It will report on:

  1. How many NOTICE files (e.g., Disclaimer, Keys, License, etc.), and which files they are;
  2. How many Apache-Licensed Files (via license headers), and which files they are;
  3. How many and which files are Binaries (generally not OK in src releases) and Standard (e.g., src)

You'll note that RAT provides excellent integration into Apache Maven and Ant, but none for Node.js builds. This means that RAT cannot be configured to automatically produce a summary report upon building UserALE.js. You'll have to run it at the command line:

Follow instructions for installing RAT and its major dependency, Maven. 

Once the RAT /BIN file is accessible, make your life much easier and append the .jar file to your $PATH:

$ export RAT=./apache-rat-project/apache-rat/target/apache-rat-0.13.jar


Now, having made your life easier, you can run RAT from the command line against a src directory or .tgz:

$ java -jar $RAT .apache-flagon-useralejs-X.Y.Z-src #runs report on target directory

$ java -jar $RAT --help #gives options


Continuing the theme of self improvement, use Regex Wildcards to exclude certain files that can't have headers or don't need to (e.g., .JSON, .md, .rdf):

$ java -jar $RAT -e ".+\\.json" -e ".+\\.md"  -d ./apache-flagon-useralejs-X.Y.Z-src


What you're looking for are src files w/o License headers (e.g., .html, .js). Your summary will look like this (note that all .JSON and .md files are excluded):

*****************************************************

Files with unapproved licenses:

  ./apache-flagon-useralejs-incubating-2.1.0-src/.babelrc #<--S'OK, this is basically JSON
  ./apache-flagon-useralejs-incubating-2.1.0-src/example/webpackUserAleExample/webpack.config.js #<--NOT OK

*****************************************************

*****************************************************
  Files with Apache License headers will be marked AL
  Binary files (which do not require any license headers) will be marked B
  Compressed archives will be marked A
  Notices, licenses etc. will be marked N
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/.asf.yaml
 !????? ./apache-flagon-useralejs-incubating-2.1.0-src/.babelrc
  N     ./apache-flagon-useralejs-incubating-2.1.0-src/DISCLAIMER
  N     ./apache-flagon-useralejs-incubating-2.1.0-src/KEYS
  N     ./apache-flagon-useralejs-incubating-2.1.0-src/LICENSE
  N     ./apache-flagon-useralejs-incubating-2.1.0-src/NOTICE
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/doap-userale.js.rdf
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/gulpfile.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/build/userale-2.1.0.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/build/userale-2.1.0.min.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/build/UserAleWebExtension/background.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/build/UserAleWebExtension/content.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/build/UserAleWebExtension/options.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/build/UserAleWebExtension/optionsPage.html
  B     ./apache-flagon-useralejs-incubating-2.1.0-src/build/UserAleWebExtension/icons/border-48.png
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/example/index.html
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/example/index.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/example/server.js
  N     ./apache-flagon-useralejs-incubating-2.1.0-src/example/webpackUserAleExample/LICENSE
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/example/webpackUserAleExample/index.html
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/example/webpackUserAleExample/index.js
 !????? ./apache-flagon-useralejs-incubating-2.1.0-src/example/webpackUserAleExample/webpack.config.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/example/webpackUserAleExample/dist/main.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/attachHandlers.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/configure.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/getInitialSettings.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/main.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/packageLogs.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/sendLogs.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/UserALEWebExtension/background.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/UserALEWebExtension/content.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/UserALEWebExtension/globals.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/UserALEWebExtension/messageTypes.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/UserALEWebExtension/options.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/UserALEWebExtension/optionsPage.html
  B     ./apache-flagon-useralejs-incubating-2.1.0-src/src/UserALEWebExtension/icons/border-48.png
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/src/UserALEWebExtension/public/index.html
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/attachHandlers_spec.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/configure_spec.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/getInitialSettings_fetchAll.html
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/getInitialSettings_spec.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/getInitialSettings_userParam.html
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/main.html
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/main_spec.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/packageLogs.html
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/packageLogs_spec.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/sendLogs_spec.js
  AL    ./apache-flagon-useralejs-incubating-2.1.0-src/test/testUtils.js


  • No labels