Experiment with JSXGraph library

A playground for course JavaScript at HTWSaar. This project uses the library JSXGraph
https://jsxgraph.uni-bayreuth.de/wp/index.html to draw mathematical objects.

0. Requirement

• Some knowledge about shell or gitbash would be useful.
• Nodejs and NPM (https://nodejs.org/en/download/). You don't need to know to use Nodejs to write Backend-JavaScript Code,
  but you should know how to install it on your computer.
• Post-Install NPM If you use Windows(TM) you may need to run

npm install --global --debug windows-build-tools

from an elevated PowerShell or CMD.exe (run as Administrator). Go back here
and do this step if you cannot go further in next steps.

All commands below are expected to be executed from the parent-directory
of this file. This is common by using NPM tool to manage dependencies and
the build process.

1. Install all dependency

Just run

npm install --omit=optional

Be careful! The command npm does not show error if you write wrong CLI flag. For example
if you write npm instal --no-options, it will silently install all Optional packages
without tell you that it cannot recognize the flag --no-options. Not so nice!

2. Code and Test routine

Unit Test in JavaScript can be split in two parts: One for Non-Browser Code, One for Browser related code.
The first part is easier to write and to execute automatically. Once needs more effort to get the last part
work. The last part can also only run semi-automatically.

2.1 Run code on a browser

To see how a HTML page should work on a browser just run

npx parcel serve <your-html-file> --open

For example

npx parcel serve src/jsxgraph-experiment.html --open

If something goes wrong, run

npm run clean-all

then

npm install omit=optional

may help.

2.2 Run AVA Unit test

Unit Test Runner of this project is AVA https://github.com/avajs/ava. To run Unit Test:

npm run test

This command calls npx nyc ava. AVA executes all Unit-Tests in directory test/, nyc
counts how much code are tested. This is called Test Coverage.

AVA uses NodeJS to execute Unit Tests, therefore it is not comfortable to write Unit Tests with
AVA to test JavaScript Code, which depends on Browser Objects, for example window, window.document, ect. One can use
QUnit https://qunitjs.com/ to (semi-automatically) run Unit Tests on Browser. To execute Browser Unit Test
firstly run

npm run test-browser

then, if the browser is not automatically opened, open a browser and navigate it to the test files.

3. Build productive Release

To build productive Release (it is code, which runs on productive system) just run

npm run build

This command creates the directory dist, which contains final code to be deployed.
One can then deploy the directory dist to, for example apache HTML directory, or
Github Pages (https://pages.github.com/)

4. Troubleshooting

• parcel does not work well with the attribute type="module" in <script type="module" src="..."></script>.
  So remove this attribute!
• If a command causes an error, try to
• remove node_modules, .cache and dist,
• reinstall all dependencies with npm install --no-optional.
• re-run the command.

5. Exercise

• How to declare a 3rd Party dependency, say lodash, in this project via NPM?
• What does npm run do? How many scripts are there in the file package.json?
• What do npm run clean and npm run clean-all do? Why do we need them?
• How to fix the error

Der Befehl "rm" ist entweder falsch geschrieben oder konnte nicht gefunden werden. 

in Windows? (Try to keep package.json working on both Unix-like and Windows
Operating Systems.)

• Which benefit do we get, as we write Unit-Test for Browser Code and Unit Test for Non-Browser Code
  separately? Theoretically, we can write Unit Test for Non-Browser Code in a Unit Test Frameworks for
  Browser. For example in this project we can just use QUnit to test all javascript files.