@castlabs/prestoplay

PRESTOplay for Browsers Version 6

The castLabs player's SDK for browsers.

General info

• We use Closure Compiler, thus we can rely on ES6. We have our own Closure build plugin for Gradle.
• We use Gradle as the project builder. A vast variety of tasks are already in place. Please check build.gradle files in / and /lib.
• We heavily rely on unit tests.

Gradle cheat sheet

Here is a quick cheat sheet for gradle:

./gradlew help # display help
./gradlew task # list all runnable Tasks

In order to use Gradle on Windows just use .\gradlew.bat to run your commands instead of ./gradle.

Installation & setup

First, make sure you have the correct versions of Java and Node.js:

java --version; # should be >= 11 and <= 17
node --version; # should be <= 16
git --version;  # should be >= 2.14

Clone the repo:

git clone --recursive [e-mail]:castlabs/prestoplay-web.git

Note: Do no attempt to clone this repo over HTTPS. If you do not have SSH set up with github, set it up first, then clone the repo. Without it, submodules will not get cloned.

Configure Git:

git config submodule.recurse true

Next, before we can install dependencies and run a build, make sure that you have configured and set up a GitHub Personal Access token (PAT) that permits read access to the packages hosted on GH. We need this to access pre-compiled dependencies. You can create one on Github -> Settings -> Developer Settings -> Personal Access Token. You can also use this link to create a read-only token.

Once you have the token, set up the following environment variables in your profile:

export GITHUB_ACTOR=<GH-username>
export GITHUB_TOKEN=<GH-PAT>

With this in place you can trigger a build.

Build

./gradlew build

To build the project, run ./gradlew :lib:deps :lib:buildDebug, but a large combination of tasks can achieve the build.

You can also run just ./gradlew buildRelease to prepare build of lib and playmaker app as well.

Before pushing any commit to this repository make sure you run:

./gradlew :lib:deps :lib:lint :lib:buildDebug :lib:buildRelease :lib:docs

first.

To run the compiled code in the browser, use an HTTP server of your choice. For example:

npx http-server -o lib/index.html

Compilation using docker

If you just want to compile library and you don't want to waste time for Java & Node setup, you can just compile through a docker container. You still need GitHub token described earlier. You can add it to your profile as described earlier.

In order to access compilation tools, you also need to login into GitHub Docker Registry, using GitHub token described earlier. To login, type:

echo "$GITHUB_TOKEN" | docker login ghcr.io -u $GITHUB_ACTOR --password-stdin

Next you can run docker compose:

docker compose up clpp-compiler

Docker image consisting PRESTOplay Web toolchain is maintained under prestoplay-builds-web repository.

API documentation

API documentation for PRESTOplay is generated from JSDoc comments in code.

To generate the API documentation run:

npm run docs

You can view the generated API documentation in the Play Maker app, run:

./gradlew :playmaker_app:serve
# And go to http://localhost:8080/#/docs

The doc which can be viewed in the Play Maker app also contains manual pages, these can be found and edited in ./playmaker_app/src/manual.

Unit testing

The basic command for running tests is:

./gradlew :lib:unitTests -Pwatch=true

This will keep the browser opened, so any changes will reload tests. Of course you can avoid this by removing the -Pwatch=true or changing it to false.

The following example adds a filter, so you can test only the case you are working on:

./gradlew :lib:unitTests -Pwatch=true -Pfilter="Tizen"

This will allow only tests described as "Tizen" to be run.

Tests lie under lib/test, and, as previously, mimics the same directory tree as the sources.

Please create unit tests for every new function/feature implemented in the player.

Also, make sure to add unit tests every time a bug is found and was not covered by the tests.

Always check the coverage page, under /dist/reports/coverage/html/index.html and make sure that files have at least 50% covered (up to the yellow bar).

Make sure to clean up any DOM elements or global variables added to your test in the afterAll and afterEach functions. Keep in mind that asynchronous operations must be taken into consideration, so a timeout must be added as a second argument to these functions.

Test params cheat sheet

Unit test script can be parametrized. For a complete list of parameters refer to task unitTests in Gradle file, the top of Karma config or Gradle properties file.

Here are some examples:

# Run in watch mode. When you edit files, tests will re-run:
./gradlew :lib:unitTests -Pwatch=true

# Run only specs that contain `Tizen` in a describe() description:
./gradlew :lib:unitTests -Pfilter="Tizen"
# Run only specs that contain `clpp.thumbnails.ThumbnailsPlugin` in a describe() description:
./gradlew :lib:unitTests -Pfilter="clpp.thumbnails.ThumbnailsPlugin"

# Run only one spec file `lib/test/plugin/thumbnails/ThumbnailProviderVtt.spec.js`
./gradlew :lib:unitTests -PfileFilter=ThumbnailProviderVtt.spec.js # or
./gradlew :lib:unitTests -PfileFilter=thumbnails/ThumbnailProviderVtt.spec.js # or
./gradlew :lib:unitTests -PfileFilter=plugin/thumbnails/ThumbnailProviderVtt.spec.js
# Run all specs in folder `lib/test/plugin/thumbnails`
./gradlew :lib:unitTests -PfileFilter='thumbnails/**/*.spec.js'

# Run and show test summary (names of all executed test cases)
./gradlew :lib:unitTests -PtestSummary=true

Debugging tests in VS Code

• Run tests in watch mode.

./gradlew :lib:unitTests -Pwatch=true

• Attach debugger (Fn + F5 on Mac).
• Place a break point.
• Edit the test that contains the break point.

Unit testing using Docker

You can use Docker to run tests on Chrome, Edge or Firefox. This approach gives access to ephemeral environment and is also used by GitHub Actions.

You need to prepare your GitHub Token and login into GitHub Docker Registry, as described earlier.

To run default tests on Chrome, Firefox & Edge, just type:

docker compose up karma.castlabs.com

If you want to i.e. run only unit tests on Firefox, run:

docker compose run --use-aliases karma.castlabs.com \
    ./gradlew unitTests -Pskip=integration -Pbrowsers=Firefox_Docker

You can go to http://localhost:4444 to see what's going on inside Selenium Grid. Password to see browser session in VNC is secret.

Keep in mind that running tests on Docker unfortunately we cannot test persistent licenses.

Release process

We release the PRESTOplay package along with the Playmaker demo app and documentation via GitHub releases and an automated pipeline. Read all about the release process here.

Build and Release workflows

We are using GitHub Actions for PRESTOplay and specifically also for this repository. The actions and their workflow definitions can be found in the workflows.

Artifacts, builds, and workflows

There are three types of workflows that we maintain:

• build-and-bundle
• test
• publish

The build-and-bundle workflows

The build and bundle workflows are responsible to compile and lint parts of the code-base, as well as the responsibility to create library and application bundles. The libraries and application bundles are used by other workflows downstream, while the lint and compilation checks are in place to abort workflow runs early and provide quick feedback.

The following artifacts are created by these workflows:

• castlabs-prestoplay-<version>.tgz is an NPM compatible tar ball that can be published with npm publish and installed with npm install.
• castlabs-prestoplay-browsers-<version>.zip is the zip bundle that can be uploaded to the downloads portal and contains the SDK as well as documentation and examples.
• playmaker-app-<version>.zip is the release version of the playmaker application that can be used to update demo.castlabs.com and other locations where that application should be published.

The test workflows

Test workflows are used to run unit and integration tests against different platforms. They operate against the entire SDK, but we maintain separate workflows for different platforms and environments.

The publish workflows

Publish workflows take the bundles prepared in the build-and-bundle workflows and publish them to final destinations. We currently support the following targets:

• GitHub NPM repository
• Official NPM repository
• castLabs Downloads Portal
• GitHub Releases of this repository
• Web distributions for internal and public

Contributing

Please read CONTRIBUTING.md for more information on the process we would like developers to follow.

Advanced topics

• Read about Git submodules
• Find more docs in Know How

Versioning

We follow SemVer since version 6.2.6, i.e. since we started publishing to NPM.

Before v6.2.6, it was possible to make breaking changes in a minor update (e.g. breaking change in v6.2.0).

Version history

version	notes
6	(current)
5	located in a separate repo, development stopped in 2020

Playmaker App

The Playmaker app is basically a mix of a player configurator + statistics + documentation. It can be used during development and for test.

Run Playmaker app in dev mode:

./gradlew :playmaker_app:serve

Build the Playmaker app from the project's root directory with:

./gradlew :playmaker_app:buildRelease

To run Playmaker App using docker (you need to login to ghcr.io registry as described earlier):

docker compose up playmaker-app

For further information read the Playmaker App README.md

Installation via NPM

PRESTOplay Web supports installation as an internal NPM package. If you need to use the player in any internal project, you can do it using NPM in just a few steps:

• Create Personal Access Token and export it in your shell as GITHUB_TOKEN env variable (described already several times).
• Configure access to GitHub Packages in your node project. You need to create an .npmrc file in main project folder and put there following lines:

  @castlabs:registry=https://npm.pkg.github.com
  //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
  

• Install package:

  npm install @castlabs/prestoplay
  

• All JS files will land in node_modules/@castlabs/prestoplay/dist folder, so they can be included in your project from there.

Licenses

In order to deploy your application to some domain a license key is needed, otherwise the player will be disabled. A list of all existing licenses can be found here.

Each license has multiple license keys attached to it. Developers can create new license keys for existing licenses, but not new licenses. In order to create a new license, admin permissions are needed (e.g. Thasso Griebel, Tomica Gril).

New customers can get a (trial) license by filling out this form.