Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oresoftware/r2g.example
r2g example project
https://github.com/oresoftware/r2g.example
nodejs npm r2g
Last synced: 24 days ago
JSON representation
r2g example project
- Host: GitHub
- URL: https://github.com/oresoftware/r2g.example
- Owner: ORESoftware
- Created: 2018-08-16T19:10:01.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2018-09-04T09:41:36.000Z (over 6 years ago)
- Last Synced: 2023-03-02T00:26:07.873Z (almost 2 years ago)
- Topics: nodejs, npm, r2g
- Language: Shell
- Homepage: https://www.youtube.com/channel/UCTupA5X6frCs5ikxLuNCc9A?view_as=subscriber
- Size: 55.7 KB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
### r2g example project - how to use r2g for publishing NPM packages
--------------------
This readme file accompanies the following video:
--------------------
Remember that there are 3 test phases, phaseZ/phaseS/phaseT.
See: https://github.com/ORESoftware/r2g
---------------------
Remember that r2g can catch at least 4 types of problems:
1. Missing dependencies - when people install your package with the `--production` and/or `--no-optional` flag, your package might be missing deps.
2. Source files that are missing in the NPM tarball: your [.npmignore](https://docs.npmjs.com/misc/developers#keeping-files-out-of-your-package)
file or ["files"](https://docs.npmjs.com/files/package.json#files) property in package.json might be too aggressive/passive.
3. Failing/forgetting to build on the current branch before publishing: It is possible to check out a VCS branch that has passed on a CI/CD platform but locally does not have the built/transpiled target files. This means the target files will not make it into the tarball that gets published to NPM.
This is probably more common when using TypeScript, but could also happen when creating a Node.js addon.
4. General/unknown problems that relate to using/running your package as a dependency, instead of directly. Most likely problems relating to file paths.
---------------------
Besides catching the above problems, r2g also has the added benefit of being one more way to test your package from a different angle.
r2g is an easy way to test your package, in the way an end user would.
-----------------------
## To learn how r2g works, do these steps in order:
1. Clone this repo:
>
>`$ git clone https://github.com/ORESoftware/r2g.example.git` and run `npm i`
>
2. Install r2g globally:
>
>`$ npm i -g r2g`
>
3. Run `$ r2g test` at the cloned project root
>
> => The first problem is that it says it can't find our package "r2g.example". That is because we haven't created the files
> in the dist folder yet. So we build/transpile with tsc. This is the first kind of problem r2g can catch.
>
4. Run `$ tsc --watch`, from the root of the project. Use `npm i -g typescript` if you don't have `tsc` installed.
5. a. Run `$ r2g test`
>
> It should fail, with exit code 1.
>
> It will output something like:
>
>```
>r2g: phase-S: You may have a missing dependency in your project, or a dependency that should be in "dependencies" not in "devDependencies".
>r2g: phase-S: /home/oleg/.r2g/temp/project/smoke-tester.js:49
>r2g: phase-S: throw err;
>r2g: phase-S: ^
>r2g: phase-S:
>r2g: phase-S: Error: Cannot find module 'rxjs'
>```
>
>
> the problem is that 'rxjs' is listed in devDependencies, but it needs to be in dependencies.
>
5. b. In package.json, move `"rxjs"` from `"devDependencies"` to `"dependencies"`, and run `$ r2g test`
>
> Now it should pass, with exit code 0.
> You might notice "foobar test" in the output, during phase-Z.
> Look in package.json at the r2g.test field, this is the default command to be run during phase-Z.
>
6. Go into package.json and change "r2g.test" to "r2g.testnot". Now, r2g will default to the `npm test` script.
>
> => In this case, `npm test` will run `node test/simple.js`
>
7. Run `$ r2g test`
>
> It will output something like:
>
>```
>r2g: phase-Z: Directory path which contains the r2g.example index file: /home/you/.r2g/temp/copy/r2g.example/dist
>```
>
8. Go into test/simple.js and switch to `require('r2g.example')` instead of `require('../dist')`, then run `$ r2g test`
>
> It will output something like:
>
>```
>r2g: phase-Z: Directory path which contains the r2g.example index file: /home/you/.r2g/temp/project/node_modules/r2g.example/dist
>```
>
9. The difference between 7 and 8 is important. 7 loads the regular unpacked version of your package, and 8 will load a
previously packed version of your package. Using 7 will `npm test` your package as usual. Using 8 will `npm test` your package
in a way that tests itself as a dependency of itself and having been previously packed with NPM pack.
10. Now, go into src/index.ts. Change `r2gSmokeTest` to `r2gSmokeTestFoo`. Run `$ r2g test`.
>
> It will output:
>
>```
>r2g: phase-S: A module failed to export a function from "main" with key "r2gSmokeTest".
>r2g: phase-S: The module/package missing this export has the following name:
>r2g: phase-S: r2g.example
>```
>
This means that your main (dist/index.js) failed to export a function with name `r2gSmokeTest`, because we changed it
to `r2gSmokeTestFoo`, lulz.
11. Change `r2gSmokeTestFoo` back to `r2gSmokeTest`, but return `false` from the function instead of `true`.
>
> It will output:
>
>```
>r2g: phase-S: At least one exported "r2gSmokeTest" function failed.
>r2g: phase-S: Error: [ { path: 'r2g.example', result: false } ]
>```
>
12. Your r2gSmokeTest function must return `true`, and no other value is acceptable. To skip phase-S, use `--skip=s` or `-s`.
As an example, you can try using this for your `r2gSmokeTest`:
```js
export const r2gSmokeTest = async () => {
const z = exports.z;
const v = await z.foo();
return v === 'foo';
}
```
Ultimately, the purpose of `r2gSmokeTest` is if you don't want to use ".r2g/tests" in your project. Next we will
create a directory in your project called .r2g which will house tests used for specifcally before publishing.
13. Run `r2g init` in your project root. You will get this new dir with this structure:
```
.r2g/
fixtures/
tests/
config.js
readme.md
```
14. The tests in the .r2g/tests folder are tests that will be copied like so:
```
project/
node_modules/
r2g.example/
.r2g/
fixtures/
tests/
```
to:
```
project/
fixtures/ # copied here
tests/ # copied here
node_modules/
r2g.example/
.r2g/
fixtures/
tests/
```
Where project is a temp directory that will load your package a dependency and run tests against it.
15. part a. Copy the following contents to `.r2g/tests/smoke-test.2.js`:
```js
#!/usr/bin/env node
'use strict';
const assert = require('assert');
const path = require('path');
const cp = require('child_process');
const os = require('os');
const fs = require('fs');
const EE = require('events');
process.on('unhandledRejection', (reason, p) => {
// unless we force process to exit with 1, process may exit with 0 upon an unhandledRejection
console.error(reason);
process.exit(1);
});
const example = require('r2g.example');
example.runZoom((err,val) => {
if(err){
throw err;
}
if(val !== true){
throw new Error('Resolved value should be true.');
}
});
```
15. part b. In `.r2g/tests/smoke-test.1.js`, you will see something like this:
```js
#!/usr/bin/env node
'use strict';
const assert = require('assert');
const path = require('path');
const cp = require('child_process');
const os = require('os');
const fs = require('fs');
const EE = require('events');
process.on('unhandledRejection', (reason, p) => {
// note: unless we force process to exit with 1, process may exit with 0 upon an unhandledRejection
console.error(reason);
process.exit(1);
});
// your test goes here
// assert.strictEqual(true, false, 'whoops');
```
Uncomment this line at the end:
```js
assert.strictEqual(true, false, 'whoops');
```
Now run `r2g test`. You will see:
>
>```
>r2g: About to run tests in your .r2g/tests dir.
>r2g: phase-T: Now we are in phase-T...
>r2g: phase-T: AssertionError [ERR_ASSERTION]: whoops
>r2g: [r2g/error] an r2g test failed => a script in this dir failed to exit with code 0: /home/you/.r2g/temp/project/tests
>```
>
Note, in order to get phase-Z to pass:
1. you will also have to remove the following line from `.npmignore`:
```
assets/zoom.sh
```
That will get .r2g/tests/smoke-test.2.js to pass.
2. Change:
```js
assert.strictEqual(true, false, 'whoops');
```
to
```js
assert.strictEqual(true, true, 'whoops');
```
That will get .r2g/tests/smoke-test.1.js to pass. Now your phase-T tests should pass.
You can add more tests to .r2g/tests folder as desired.
__________________________________________________________________
### In Conclusion:
You have now seen how the basic three phases work, S,Z,T.
To learn more about the `--full` option, we will save that for another day.
We will also save examples of testing CLI applications for another day, however, testing CLI apps won't be
that much different from testing importable libraries.