{"id":17749531,"url":"https://github.com/oresoftware/r2g.example","last_synced_at":"2025-04-01T08:11:33.652Z","repository":{"id":95713044,"uuid":"145028842","full_name":"ORESoftware/r2g.example","owner":"ORESoftware","description":"r2g example project","archived":false,"fork":false,"pushed_at":"2018-09-04T09:41:36.000Z","size":57,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2023-03-02T00:26:07.873Z","etag":null,"topics":["nodejs","npm","r2g"],"latest_commit_sha":null,"homepage":"https://www.youtube.com/channel/UCTupA5X6frCs5ikxLuNCc9A?view_as=subscriber","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ORESoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-16T19:10:01.000Z","updated_at":"2018-09-04T09:41:37.000Z","dependencies_parsed_at":"2023-05-21T17:45:24.979Z","dependency_job_id":null,"html_url":"https://github.com/ORESoftware/r2g.example","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fr2g.example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fr2g.example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fr2g.example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fr2g.example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ORESoftware","download_url":"https://codeload.github.com/ORESoftware/r2g.example/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246604611,"owners_count":20804100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nodejs","npm","r2g"],"created_at":"2024-10-26T11:23:38.487Z","updated_at":"2025-04-01T08:11:33.634Z","avatar_url":"https://github.com/ORESoftware.png","language":"Shell","readme":"\n### r2g example project - how to use r2g for publishing NPM packages\n\n--------------------\n\nThis readme file accompanies the following video:\n\n\n--------------------\n\nRemember that there are 3 test phases, phaseZ/phaseS/phaseT. \u003cbr\u003e\nSee: https://github.com/ORESoftware/r2g\n\n---------------------\n\nRemember that r2g can catch at least 4 types of problems:\n\n1. Missing dependencies - when people install your package with the `--production` and/or `--no-optional` flag, your package might be missing deps.\n2. Source files that are missing in the NPM tarball: your [.npmignore](https://docs.npmjs.com/misc/developers#keeping-files-out-of-your-package) \nfile or [\"files\"](https://docs.npmjs.com/files/package.json#files) property in package.json might be too aggressive/passive.\n3. 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. \nThis is probably more common when using TypeScript, but could also happen when creating a Node.js addon.\n4. General/unknown problems that relate to using/running your package as a dependency, instead of directly. Most likely problems relating to file paths.\n\n---------------------\n\nBesides catching the above problems, r2g also has the added benefit of being one more way to test your package from a different angle.\nr2g is an easy way to test your package, in the way an end user would.\n\n-----------------------\n\n## To learn how r2g works, do these steps in order:\n\n\u003cbr\u003e\n\n1. \u003cb\u003e Clone this repo: \n\n\u003e\n\u003e`$ git clone https://github.com/ORESoftware/r2g.example.git` and run `npm i` \u003c/b\u003e\n\u003e\n\n\u003cbr\u003e\n\n2. \u003cb\u003e Install r2g globally: \n\n\u003e\n\u003e`$ npm i -g r2g`\n\u003e\n\n\u003cbr\u003e\n\n3. \u003cb\u003e Run `$ r2g test` at the cloned project root \u003c/b\u003e\n\n\u003e\n\u003e  =\u003e The first problem is that it says it can't find our package \"r2g.example\". That is because we haven't created the files\n\u003e   in the dist folder yet. So we build/transpile with tsc. This is the first kind of problem r2g can catch.\n\u003e\n\n\u003cbr\u003e\n \n4. \u003cb\u003e Run `$ tsc --watch`, from the root of the project. Use `npm i -g typescript` if you don't have `tsc` installed.  \u003c/b\u003e\n\n\u003cbr\u003e\n\n5. a. \u003cb\u003e Run `$ r2g test` \u003c/b\u003e\n\n\u003e\n\u003e  It should fail, with exit code 1.\n\u003e\n\u003e  \u003cb\u003e It will output something like: \u003c/b\u003e \n\u003e\n\u003e```\n\u003er2g: phase-S: You may have a missing dependency in your project, or a dependency that should be in \"dependencies\" not in \"devDependencies\".\n\u003er2g: phase-S: /home/oleg/.r2g/temp/project/smoke-tester.js:49\n\u003er2g: phase-S:             throw err;\n\u003er2g: phase-S:             ^\n\u003er2g: phase-S: \n\u003er2g: phase-S: Error: Cannot find module 'rxjs'\n\u003e```\n\u003e\n\u003e  \u003cbr\u003e\n\u003e  \u003cb\u003e the problem is that 'rxjs' is listed in devDependencies, but it needs to be in dependencies. \u003c/b\u003e\n\u003e\n\n5. b. \u003cb\u003e In package.json, move `\"rxjs\"` from `\"devDependencies\"` to `\"dependencies\"`, and run `$ r2g test` \u003c/b\u003e\n\n\u003e\n\u003e  Now it should pass, with exit code 0.\n\u003e  You might notice \"foobar test\" in the output, during phase-Z.\n\u003e  Look in package.json at the r2g.test field, this is the default command to be run during phase-Z.\n\u003e\n\n\u003cbr\u003e\n\n6. \u003cb\u003e Go into package.json and change \"r2g.test\" to \"r2g.testnot\". Now, r2g will default to the `npm test` script. \u003c/b\u003e\n\n\u003e\n\u003e  =\u003e In this case, `npm test` will run `node test/simple.js`\n\u003e\n\n\u003cbr\u003e\n\n7. \u003cb\u003e Run `$ r2g test` \u003c/b\u003e\n\n\u003e\n\u003e  \u003cb\u003e It will output something like: \u003c/b\u003e\n\u003e\n\u003e```\n\u003er2g: phase-Z: Directory path which contains the r2g.example index file: /home/you/.r2g/temp/copy/r2g.example/dist\n\u003e```\n\u003e\n\n\u003cbr\u003e\n\n8. \u003cb\u003e Go into test/simple.js and switch to `require('r2g.example')` instead of `require('../dist')`, then run `$ r2g test` \u003c/b\u003e\n\n\u003e\n\u003e  \u003cb\u003e It will output something like: \u003c/b\u003e\n\u003e\n\u003e```\n\u003er2g: phase-Z: Directory path which contains the r2g.example index file: /home/you/.r2g/temp/project/node_modules/r2g.example/dist\n\u003e```\n\u003e\n\n\u003cbr\u003e\n\n9. \u003cb\u003e The difference between 7 and 8 is important. 7 loads the regular unpacked version of your package, and 8 will load a\npreviously packed version of your package. Using 7 will `npm test` your package as usual. Using 8 will `npm test` your package\nin a way that tests itself as a dependency of itself and having been previously packed with NPM pack. \u003c/b\u003e\n\n\u003cbr\u003e\n\n10. \u003cb\u003e Now, go into src/index.ts. Change `r2gSmokeTest` to `r2gSmokeTestFoo`. Run `$ r2g test`. \u003c/b\u003e\n\n\u003e\n\u003e  \u003cb\u003e It will output: \u003c/b\u003e\n\u003e   \n\u003e```\n\u003er2g: phase-S: A module failed to export a function from \"main\" with key \"r2gSmokeTest\".\n\u003er2g: phase-S: The module/package missing this export has the following name:\n\u003er2g: phase-S: r2g.example\n\u003e```\n\u003e\n\nThis means that your main (dist/index.js) failed to export a function with name `r2gSmokeTest`, because we changed it\nto `r2gSmokeTestFoo`, lulz.\n\n\u003cbr\u003e\n\n11. \u003cb\u003e Change `r2gSmokeTestFoo` back to `r2gSmokeTest`, but return `false` from the function instead of `true`. \u003c/b\u003e\n\n\u003e\n\u003e  \u003cb\u003e It will output: \u003c/b\u003e\n\u003e   \n\u003e```\n\u003er2g: phase-S: At least one exported \"r2gSmokeTest\" function failed.\n\u003er2g: phase-S: Error: [ { path: 'r2g.example', result: false } ]\n\u003e```\n\u003e\n\n\u003cbr\u003e\n\n12. \u003cb\u003e Your r2gSmokeTest function must return `true`, and no other value is acceptable. To skip phase-S, use `--skip=s` or `-s`. \u003c/b\u003e\n\n\u003cbr\u003e\n\nAs an example, you can try using this for your `r2gSmokeTest`:\n\n```js\nexport const r2gSmokeTest = async () =\u003e {\n  const z = exports.z;\n  const v = await z.foo();\n  return v === 'foo';\n}\n```\n\nUltimately, the purpose of `r2gSmokeTest` is if you don't want to use \".r2g/tests\" in your project. Next we will\ncreate a directory in your project called .r2g which will house tests used for specifcally before publishing. \u003c/b\u003e\n\n\u003cbr\u003e\n\n13. \u003cb\u003e Run `r2g init` in your project root. You will get this new dir with this structure: \u003c/b\u003e\n\n```\n.r2g/\n  fixtures/\n  tests/\n  config.js\n  readme.md\n```\n\u003cbr\u003e\n\n14. \u003cb\u003e The tests in the .r2g/tests folder are tests that will be copied like so: \u003c/b\u003e\n\n```\nproject/\n node_modules/\n  r2g.example/\n    .r2g/\n      fixtures/\n      tests/\n```\n\nto:\n\n```\nproject/\n fixtures/    # copied here\n tests/       # copied here\n node_modules/\n  r2g.example/\n    .r2g/\n      fixtures/\n      tests/\n```\n\nWhere project is a temp directory that will load your package a dependency and run tests against it.\n\n\u003cbr\u003e\n\n15. part a. Copy the following contents to `.r2g/tests/smoke-test.2.js`:\n\n```js\n#!/usr/bin/env node\n'use strict';\n\nconst assert = require('assert');\nconst path = require('path');\nconst cp = require('child_process');\nconst os = require('os');\nconst fs = require('fs');\nconst EE = require('events');\n\n\nprocess.on('unhandledRejection', (reason, p) =\u003e {\n  // unless we force process to exit with 1, process may exit with 0 upon an unhandledRejection\n  console.error(reason);\n  process.exit(1);\n});\n\n\nconst example = require('r2g.example');\n\nexample.runZoom((err,val) =\u003e {\n  \n  if(err){\n    throw err;\n  }\n  \n  if(val !== true){\n    throw new Error('Resolved value should be true.');\n  }\n  \n});\n\n```\n\n\n15. part b. \u003cb\u003e In `.r2g/tests/smoke-test.1.js`, you will see something like this: \u003c/b\u003e\n\n```js\n#!/usr/bin/env node\n'use strict';\n\nconst assert = require('assert');\nconst path = require('path');\nconst cp = require('child_process');\nconst os = require('os');\nconst fs = require('fs');\nconst EE = require('events');\n\nprocess.on('unhandledRejection', (reason, p) =\u003e {\n  // note: unless we force process to exit with 1, process may exit with 0 upon an unhandledRejection\n  console.error(reason);\n  process.exit(1);\n});\n\n// your test goes here\n// assert.strictEqual(true, false, 'whoops');\n```\n\u003cbr\u003e\n\nUncomment this line at the end:\n\n```js\nassert.strictEqual(true, false, 'whoops');\n```\n\n\u003cbr\u003e\n\nNow run `r2g test`. You will see:\n\n\u003e\n\u003e```\n\u003er2g: About to run tests in your .r2g/tests dir.\n\u003er2g: phase-T: Now we are in phase-T...\n\u003er2g: phase-T: AssertionError [ERR_ASSERTION]: whoops\n\u003er2g: [r2g/error] an r2g test failed =\u003e a script in this dir failed to exit with code 0: /home/you/.r2g/temp/project/tests\n\u003e```\n\u003e\n\n\u003cbr\u003e\n\nNote, in order to get phase-Z to pass:\n\n1. you will \u003cb\u003ealso\u003c/b\u003e have to remove the following line from `.npmignore`:\n\n\u003cbr\u003e\n\n```\nassets/zoom.sh\n```\n\nThat will get .r2g/tests/smoke-test.2.js to pass.\n\n\u003cbr\u003e\n\n2. Change:\n\n```js\nassert.strictEqual(true, false, 'whoops');\n```\n\nto\n\n```js\nassert.strictEqual(true, true, 'whoops');\n```\n\nThat will get .r2g/tests/smoke-test.1.js to pass. Now your phase-T tests should pass. \nYou can add more tests to .r2g/tests folder as desired. \n\n__________________________________________________________________\n\n\u003cbr\u003e\n\n### In Conclusion:\n\nYou have now seen how the basic three phases work, S,Z,T.\n\n\u003cbr\u003e\n\nTo learn more about the `--full`  option, we will save that for another day.\n\n\u003cbr\u003e \n\nWe will also save examples of testing CLI applications for another day, however, testing CLI apps won't be\nthat much different from testing importable libraries.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foresoftware%2Fr2g.example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foresoftware%2Fr2g.example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foresoftware%2Fr2g.example/lists"}