Perspective is organized as a monorepo,
and uses lerna to manage dependencies. The
@finos/perspective modules has an additional, unmanaged dependency
however; the Emscripten compiler, which
is used to compile the core C++ engine to WebAssembly, and must be installed
Building via Docker
For convenience, Perspective provides a Docker container for this; To use it, you only need to install Docker itself, then build perspective via:
yarn PSP_DOCKER=1 yarn build
If everything is successful, you should be able to run any of the
examples/simple like so:
yarn start simple
Building via EMSDK
If you don't want to use Docker for the build, you'll need to install the
emscripten SDK, then activate and export the latest
emsdk environment via
OSX specific instructions
Installing and activating the latest emscripten SDK:
./emsdk install latest ./emsdk activate latest
You'll also need Boost and CMake, which can be installed from Homebrew:
brew install cmake brew install boost
Windows 10 specific instructions
You need to use bash in order to build Perspective packages. To successfully build on Windows 10, enable Windows Subsystem for Linux (WSL) and install the linux distribution of your choice.
Create symbolic link to easily access Windows directories and projects modified via Windows. This way you can modify any of the Perspective files using your favorite editors on Windows and build via Linux.
Follow the Linux specific instructions to install Emscripten and all prerequisite tools.
When installing Emscripten, make sure to follow Linux specific instructions.
On Ubuntu, cmake will mistakenly resolve the system headers in
rather than the emscripten supplied versions. You can resolve this by moving
boost to somewhere other than
/use/include - into perspective's own
for example (as per here).
apt-get install libboost-all-dev cp -r /usr/include/boost ./packages/perspective/src/include/
Whichever method you choose, the build script respects a few environment flags:
PSP_DOCKERwill compile C++ source via an Emscripten Docker container.
PSP_DEBUGwill run a debug build of the C++ source.
PSP_CPU_COUNTwill set the concurrency limit for the build.
PACKAGEwill restrict the build to only specific
You can run the test suite simply with the standard NPM command, which will both build the test suite for every package and run them.
A Test name regex can be passed to
jest via the same
yarn test -t 'button test (A|B)'
The test suite is composed of two sections: a Node.js test which asserts
behavior of the
@finos/perspective library, and a suite of
Puppeteer tests which
assert the behavior of the rest of the UI facing packages. For the latter,
you'll need Docker installed, as these tests use a Puppeteer and Chrome build
installed in a Docker container.
The Puppeteer/UI tests are a form of characterization tests
which use screenshots to compare current and previous behavior of
and its plugins. The results of the each comparison are stored in each
test/results/results.json file, and the screenshots themselves are
stroed in the package's
screenshots/ directory, though only the former should
be checked in to GIT. When a test in these suites fails, a
file.diff.png are also generated, showing the divergent screenshot and a
contrast diff respectively, so you can verify that the changed behavior
either does or does not reflect your patch. If you're confident that the
screenshots reflect your change, you can update the new hashes manually in the
test/results/results.json file, or update all hashes with the
yarn test --write
For quick local iteration and debugging failing tests, the puppeteer tests can
use a local copy of Puppeteer, rather than relying on the supplied Docker image.
These will run much quicker, and can be optionally run without
mode for debugging test failures quickly. However, due to rendering
inconsistencies between platforms, the resulting test hashes will not match the
ones saved in
results.json, so you will need to re-run the suite with the
--write flag to generate a
results.local.json file specific to your OS.
To toggle between Local and Docker Puppeteer, run
This will install a local copy of puppeteer via
yarn the first time it is run,
if a local puppeteer is not found.
You can generate benchmarks specific to your machine's OS and CPU architecture
with Perspective's benchmark suite, which will generate a
report.html file in
build/ directory of every package which supports benchmarks, as well as a
results.json file in the
bench/results/, which can be checked in to GIT
with your changes to preserve them for future comparison.
--limit <NUMBER> flag to control the number of Perspective versions that the
benchmark suite will run, where
<NUMBER> is an integer greater than 0. If
cannot be parsed, is 0, or is greater than the number of versions, the benchmark suite
will run all previous versions of Perspective.
The benchmarks report and
results.json show a historgram of current
performance, as well as that of the previous
results.json. Running this
should probably be standard practice after making a large change which may
affect performance, but please create a baseline
results.json entry for your
test machine on a commit before your changes first, such that the effects of your
PR can be properly compared.