# 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

```bash
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 

```bash
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 

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

For example 

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

If something goes wrong, run 

```bash
npm run clean-all
``` 

then 

```bash
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:

```bash
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

```bash
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

```bash
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.