{"id":18437211,"url":"https://github.com/power-assert-js/espower","last_synced_at":"2025-04-10T02:22:26.630Z","repository":{"id":10175657,"uuid":"12260922","full_name":"power-assert-js/espower","owner":"power-assert-js","description":"Power Assert feature instrumentor based on the ECMAScript AST.","archived":false,"fork":false,"pushed_at":"2023-01-06T14:05:34.000Z","size":2355,"stargazers_count":59,"open_issues_count":9,"forks_count":6,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-03T00:06:26.379Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/power-assert-js.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"MIT-LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-21T04:10:52.000Z","updated_at":"2023-07-02T07:23:11.000Z","dependencies_parsed_at":"2023-01-13T15:47:02.000Z","dependency_job_id":null,"html_url":"https://github.com/power-assert-js/espower","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/power-assert-js%2Fespower","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/power-assert-js%2Fespower/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/power-assert-js%2Fespower/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/power-assert-js%2Fespower/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/power-assert-js","download_url":"https://codeload.github.com/power-assert-js/espower/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248143213,"owners_count":21054732,"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":[],"created_at":"2024-11-06T06:14:06.044Z","updated_at":"2025-04-10T02:22:26.606Z","avatar_url":"https://github.com/power-assert-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"espower\n================================\n\n[![Build Status][travis-image]][travis-url]\n[![NPM package][npm-image]][npm-url]\n[![Coverage Status][coverage-image]][coverage-url]\n[![Code Climate][codeclimate-image]][codeclimate-url]\n[![Code Style][style-image]][style-url]\n[![License][license-image]][license-url]\n\n\nPower Assert feature instrumentor based on the [ECMAScript AST](https://github.com/estree/estree).\n\n\nDESCRIPTION\n---------------------------------------\n`espower` is a core module of [power-assert](https://github.com/power-assert-js/power-assert) family. \n\n\n`espower` detects and manipulates assertion expression (JavaScript Code) in the form of ECMAScript AST defined in [The ESTree Spec](https://github.com/estree/estree) (formerly known as [Mozilla SpiderMonkey Parser API](https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API)), to instrument power-assert feature into returned new AST object. AST in, AST out. Since 0.11.0, `espower` can transform ES6 AST as well.\n\n\nPull-requests, issue reports and patches are always welcomed. See [power-assert](https://github.com/power-assert-js/power-assert) project for more documentation.\n\n\nCHANGELOG\n---------------------------------------\nSee [CHANGELOG](https://github.com/power-assert-js/espower/blob/master/CHANGELOG.md)\n\n\nAPI\n---------------------------------------\n\n### const modifiedAst = espower(ast, [options])\n\n| return type |\n|:------------|\n| `object`    |\n\n`espower` function manipulates `ast` then returns `modifiedAst` that is also an AST node object defined in [The ESTree Spec](https://github.com/estree/estree). `ast` will be manipulated directly and returned `modifiedAst` will be the same instance of `ast`.\n\n`espower` function throws `Error` when\n\n* `ast` is already instrumented\n* `ast` does not contain location information\n* `options` argument is not valid\n\n\n### const visitor = espower.createVisitor(ast, [options])\n\n| return type |\n|:------------|\n| `object`    |\n\n`espower.createVisitor` generates visitor object to be used with `estraverse.replace`. Arguments are the same as `espower` function.\n\n\n#### ast\n\n| type     | default value |\n|:---------|:--------------|\n| `object` | N/A           |\n\n`ast` should be an AST node object defined in [The ESTree Spec](https://github.com/estree/estree).\n\n\n#### options\n\n| type     | default value |\n|:---------|:--------------|\n| `object` | (return value of `espower.defaultOptions()`) |\n\nConfiguration options. If not passed, default options will be used.\n\n\n#### options.patterns\n\n| type                | default value       |\n|:--------------------|:--------------------|\n| `Array` of `string` | objects shown below |\n\n```javascript\n[\n    'assert(value, [message])',\n    'assert.ok(value, [message])',\n    'assert.equal(actual, expected, [message])',\n    'assert.notEqual(actual, expected, [message])',\n    'assert.strictEqual(actual, expected, [message])',\n    'assert.notStrictEqual(actual, expected, [message])',\n    'assert.deepEqual(actual, expected, [message])',\n    'assert.notDeepEqual(actual, expected, [message])',\n    'assert.deepStrictEqual(actual, expected, [message])',\n    'assert.notDeepStrictEqual(actual, expected, [message])'\n]\n```\n\nTarget patterns for power assert feature instrumentation.\n\nIf callee name (for example, `assert.equal`) matches exactly and number of arguments is satisfied, then the assertion will be modified.\nAny arguments enclosed in bracket (for example, `[message]`) means optional parameters. Without bracket means mandatory parameters.\n\n\n#### options.ecmaVersion\n\n| type     | default value |\n|:---------|:--------------|\n| `number` | `2018`        |\n\nThe ECMAScript version to parse and analyze. Must be either 3, 5, 6 (2015), 2016, 2017, or 2018.\n\n\n#### options.sourceType\n\n| type     | default value |\n|:---------|:--------------|\n| `string` | `'module'`    |\n\nThe source type of the code. Must be either `\"script\"` or `\"module\"`.\n\n \n#### (optional) options.path\n\n| type     | default value |\n|:---------|:--------------|\n| `string` | N/A           |\n\nFilepath of `originalAst`. If passed, espower stores filepath information for reporting. If `options.path` is absolute and it conflicts with `options.sourceRoot` or `sourceRoot` in `options.sourceMap`, then filepath in power-assert output will be fall back on `basename` of `options.path`. This property is optional.\n\n\n#### (optional) options.sourceRoot\n\n| type     | default value |\n|:---------|:--------------|\n| `string` | N/A           |\n\nRoot filepath for target test files. Only works with `options.path` or `options.sourceMap`. If set, filepath in power-assert output will be relative from `options.sourceRoot`. When both `options.sourceRoot` and sourceMap's sourceRoot are given and both are absolute filepath, `options.sourceRoot` has precedence over sourceMap's sourceRoot. This property is optional.\n\n\n#### (optional) options.sourceMap\n\n| type                | default value |\n|:--------------------|:--------------|\n| `object` or `string`| N/A           |\n\nA raw (either as a string which can be JSON.parse'd, or an object) [SourceMap](https://github.com/mozilla/source-map/) associated with `originalAst`. This property is optional. If given, espower uses `options.sourceMap` to adjust information in the power-assert output.\n\n\n#### (optional) options.visitorKeys\n\n| type     | default value |\n|:---------|:--------------|\n| `object` | N/A           |\n\nVisitorKeys for AST traversal. See [estraverse.VisitorKeys](https://github.com/estools/estraverse/blob/4.0.0/estraverse.js#L217-L288) and [babel.types.VISITOR_KEYS](https://github.com/babel/babel/blob/v5.1.13/src/babel/types/visitor-keys.json).\n\n\n#### (optional) options.parse\n\n| type                | default value |\n|:--------------------|:--------------|\n| `function`          | N/A           |\n\nA function to parse pattern string specified by `options.patterns`. This property is optional and only required to parse a bit complicated custom pattern string like \"browser.assert.element(selection, [message])\".\n\n\n### const options = espower.defaultOptions();\n\nReturns default options object for `espower` function. In other words, returns\n\n```javascript\n{\n    ecmaVersion: 2018,\n    sourceType: 'module',\n    patterns: [\n        'assert(value, [message])',\n        'assert.ok(value, [message])',\n        'assert.equal(actual, expected, [message])',\n        'assert.notEqual(actual, expected, [message])',\n        'assert.strictEqual(actual, expected, [message])',\n        'assert.notStrictEqual(actual, expected, [message])',\n        'assert.deepEqual(actual, expected, [message])',\n        'assert.notDeepEqual(actual, expected, [message])',\n        'assert.deepStrictEqual(actual, expected, [message])',\n        'assert.notDeepStrictEqual(actual, expected, [message])'\n    ]\n}\n```\n\n\nEXAMPLE\n---------------------------------------\n\nFor given test file `example_test.js` below,\n\n```javascript\nconst assert = require('power-assert');\nconst truthy = 'true';\nconst falsy = 'false';\nassert(falsy);\nassert.equal(truthy, falsy);\n```\n\nApply `espower` then generate modified code to console,\n\n```javascript\nconst espower = require('espower');\nconst esprima = require('esprima');\nconst escodegen = require('escodegen');\nconst fs = require('fs');\nconst { join } = require('path');\n\nconst filepath = join(__dirname, 'example_test.js');\nconst jsAst = esprima.parse(fs.readFileSync(filepath), {tolerant: true, loc: true, tokens: true});\nconst modifiedAst = espower(jsAst, {path: filepath, sourceRoot: __dirname});\n\nconsole.log(escodegen.generate(modifiedAst));\n```\n\nOutput:\n\n```javascript\nTBD\n```\n\n\nINSTALL\n---------------------------------------\n\n### via npm\n\nInstall\n\n    $ npm install --save-dev espower\n\n\nOUR SUPPORT POLICY\n---------------------------------------\n\nWe support Node under maintenance. In other words, we stop supporting old Node version when [their maintenance ends](https://github.com/nodejs/LTS).\n\nThis means that any other environment is not supported.\n\nNOTE: If espower works in any of the unsupported environments, it is purely coincidental and has no bearing on future compatibility. Use at your own risk.\n\n\nAUTHOR\n---------------------------------------\n* [Takuto Wada](https://github.com/twada)\n\n\nCONTRIBUTORS\n---------------------------------------\n* [James Talmage (jamestalmage)](https://github.com/jamestalmage)\n\n\nLICENSE\n---------------------------------------\nLicensed under the [MIT](https://github.com/power-assert-js/espower/blob/master/MIT-LICENSE.txt) license.\n\n\n[npm-url]: https://npmjs.org/package/espower\n[npm-image]: https://badge.fury.io/js/espower.svg\n\n[travis-url]: https://travis-ci.org/power-assert-js/espower\n[travis-image]: https://secure.travis-ci.org/power-assert-js/espower.svg?branch=master\n\n[license-url]: https://github.com/power-assert-js/espower/blob/master/MIT-LICENSE.txt\n[license-image]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat\n\n[codeclimate-url]: https://codeclimate.com/github/power-assert-js/espower\n[codeclimate-image]: https://codeclimate.com/github/power-assert-js/espower/badges/gpa.svg\n\n[coverage-url]: https://coveralls.io/r/power-assert-js/espower?branch=master\n[coverage-image]: https://coveralls.io/repos/power-assert-js/espower/badge.svg?branch=master\n\n[style-url]: https://github.com/Flet/semistandard\n[style-image]: https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpower-assert-js%2Fespower","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpower-assert-js%2Fespower","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpower-assert-js%2Fespower/lists"}