phptest 0.0.1

package/.github/workflows/main.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+
+        strategy:
+            matrix:
+                node-version: [12.x, 14.x, 16.x]
+
+        steps:
+            # Check out the repository under $GITHUB_WORKSPACE, so this job can access it
+            - uses: actions/checkout@v2
+
+            - name: Use Node.js ${{ matrix.node-version }}
+              uses: actions/setup-node@v1
+              with:
+                  node-version: ${{ matrix.node-version }}
+
+            - name: Install NPM dependencies
+              run: npm ci
+
+            - name: Run tests
+              run: npm test

package/.jshintignore

@@ -0,0 +1 @@
+/node_modules

package/.jshintrc

@@ -0,0 +1,31 @@
+{
+    "bitwise": true,
+    "curly": true,
+    "eqeqeq": true,
+    "evil": true,
+    "expr": true,
+    "forin": true,
+    "globals": {
+        "afterEach": false,
+        "beforeEach": false,
+        "describe": false,
+        "it": false
+    },
+    "immed": true,
+    "indent": 4,
+    "latedef": true,
+    "maxlen": false,
+    "maxparams": false,
+    "newcap": true,
+    "noarg": true,
+    "node": true,
+    "noempty": true,
+    "nonew": true,
+    "plusplus": false,
+    "quotmark": "single",
+    "trailing": true,
+    "undef": true,
+    "unused": true,
+    "strict": true,
+    "esversion": 8
+}

package/MIT-LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright 2022 Dan Phillimore (asmblah)
+https://github.com/uniter/phptest/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# PHPTest
+
+[![Build Status](https://github.com/uniter/phptest/workflows/CI/badge.svg)](https://github.com/uniter/phptest/actions?query=workflow%3ACI)
+
+Test helper library for PHP core runtime components.
+
+Contains shared test helper logic between [Uniter][] components such as [PHPCore][] and [PHPRuntime][].
+
+[Uniter]: https://github.com/asmblah/uniter
+[PHPCore]: https://github.com/uniter/phpcore
+[PHPRuntime]: https://github.com/uniter/phpruntime

package/index.js

@@ -0,0 +1,16 @@
+/*
+ * PHPTest - Test helper library for PHP core runtime components
+ * Copyright (c) Dan Phillimore (asmblah)
+ * https://github.com/uniter/phptest/
+ *
+ * Released under the MIT license
+ * https://github.com/uniter/phptest/raw/master/MIT-LICENSE.txt
+ */
+
+'use strict';
+
+var createIntegrationTools = require('./src/createIntegrationTools');
+
+module.exports = {
+    createIntegrationTools: createIntegrationTools
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "version": "0.0.1",
+  "name": "phptest",
+  "description": "Test helper library for PHP core runtime components",
+  "keywords": [
+    "php",
+    "test",
+    "uniter"
+  ],
+  "homepage": "https://github.com/uniter/phptest",
+  "author": "Dan Phillimore <dan@ovms.co> (https://github.com/asmblah)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uniter/phptest"
+  },
+  "bugs": {
+    "email": "dan@ovms.co",
+    "url": "https://github.com/uniter/phptest/issues"
+  },
+  "main": "index",
+  "scripts": {
+    "jshint": "jshint .",
+    "test": "npm run jshint"
+  },
+  "dependencies": {
+    "es6-weak-map": "^2.0.3",
+    "is-promise": "^4.0.0",
+    "jshint": "^2.13.4",
+    "lie": "^3.3.0",
+    "microdash": "^1.4.2",
+    "regexp.escape": "^1.1.0",
+    "source-map": "^0.7.3"
+  },
+  "peerDependencies": {
+    "core-js-pure": "^3.21.1",
+    "mocha": "^9.2.2",
+    "phpcore": "^7.1.0",
+    "phptoast": "^9.0.1",
+    "phptojs": "^9.0.0"
+  },
+  "engines": {
+    "node": ">=12"
+  },
+  "license": "MIT"
+}

package/src/createIntegrationTools.js

@@ -0,0 +1,298 @@
+/*
+ * PHPTest - Test helper library for PHP core runtime components
+ * Copyright (c) Dan Phillimore (asmblah)
+ * https://github.com/uniter/phptest/
+ *
+ * Released under the MIT license
+ * https://github.com/uniter/phptest/raw/master/MIT-LICENSE.txt
+ */
+
+'use strict';
+
+var _ = require('microdash'),
+    escapeRegex = require('regexp.escape'),
+    path = require('path'),
+    mochaPath = path.dirname(require.resolve('mocha/package.json')),
+    phpCorePath = path.resolve(__dirname, '../..'),
+    phpToAST = require('phptoast'),
+    phpToJS = require('phptojs'),
+    util = require('util'),
+    OpcodeExecutor = require('phpcore/src/Core/Opcode/Handler/OpcodeExecutor'),
+    Reference = require('../../src/Reference/Reference'),
+    SourceMapConsumer = require('source-map').SourceMapConsumer,
+    Value = require('../../src/Value').sync(),
+    Variable = require('../../src/Variable').sync(),
+    WeakMap = require('es6-weak-map'),
+    runtimeFactory = require('../../src/shared/runtimeFactory');
+
+/**
+ * Creates an integration test helper tools object.
+ *
+ * @param {Function} initRuntime
+ * @returns {Object}
+ */
+module.exports = function (initRuntime) {
+    // A map that allows looking up the source map data for a module later on
+    var moduleDataMap = new WeakMap(),
+        /**
+         * Creates a Runtime with the given mode.
+         *
+         * @param {string} mode
+         * @returns {Runtime}
+         */
+        createRuntime = function (mode) {
+            return initRuntime(runtimeFactory.create(mode));
+        },
+
+        createAsyncRuntime = function () {
+            // Create an isolated runtime we can install builtins into without affecting the main singleton one.
+            return createRuntime('async');
+        },
+        createPsyncRuntime = function () {
+            // Create an isolated runtime we can install builtins into without affecting the main singleton one.
+            return createRuntime('psync');
+        },
+        createSyncRuntime = function () {
+            // Create an isolated runtime we can install builtins into without affecting the main singleton one.
+            return createRuntime('sync');
+        },
+
+        transpile = function (path, php, phpCore, options) {
+            var transpiledResult,
+                module,
+                phpParser,
+                phpToJSBaseOptions;
+
+            options = options || {};
+            path = path || null;
+
+            phpParser = phpToAST.create(null, _.extend({
+                // Capture offsets of all nodes for line tracking
+                captureAllBounds: true
+            }, options.phpToAST));
+
+            if (path) {
+                phpParser.getState().setPath(path);
+            }
+
+            phpToJSBaseOptions = {
+                // Record line numbers for statements/expressions
+                lineNumbers: true,
+
+                path: path,
+
+                prefix: 'return '
+            };
+
+            if (options.sourceMap) {
+                // Generate a source map if specified in test options
+                _.extend(phpToJSBaseOptions, {
+                    sourceMap: {
+                        sourceContent: php,
+                        returnMap: true
+                    }
+                });
+            }
+
+            transpiledResult = phpToJS.transpile(
+                phpParser.parse(php),
+                _.extend(phpToJSBaseOptions, options.phpToJS),
+                options.transpiler
+            );
+
+            module = new Function('require', options.sourceMap ? transpiledResult.code : transpiledResult)(function () {
+                return phpCore;
+            });
+
+            if (path !== null) {
+                module = module.using({
+                    path: path
+                });
+            }
+
+            if (options.sourceMap) {
+                // Allow source map data to be looked up later (see .normaliseStack(...))
+                moduleDataMap.set(module, {sourceMapGenerator: transpiledResult.map, path: path});
+            }
+
+            return module;
+        },
+
+        // Create isolated runtimes to be shared by all tests that don't create their own,
+        // to avoid modifying the singleton module exports.
+        asyncRuntime = createAsyncRuntime(),
+        psyncRuntime = createPsyncRuntime(),
+        syncRuntime = createSyncRuntime(),
+
+        // Errors from a Function constructor-created function may be offset by the function signature
+        // (currently 2), so we need to calculate this in order to adjust for source mapping below
+        // (Note that the unused "require" arg is given so that the signature matches the Function(...) eval above)
+        errorStackLineOffset = new Function(
+            'require',
+            'return new Error().stack;'
+        )()
+            .match(/<anonymous>:(\d+):\d+/)[1] - 1;
+
+    if (!initRuntime) {
+        initRuntime = function (runtime) {
+            return runtime;
+        };
+    }
+
+    // Force all opcodes to be async for all async mode tests, to help ensure async handling is in place.
+    asyncRuntime.install({
+        serviceGroups: [
+            function (internals) {
+                var get = internals.getServiceFetcher();
+
+                // As we'll be overriding the "opcode_executor" service.
+                internals.allowServiceOverride();
+
+                return {
+                    'opcode_executor': function () {
+                        var referenceFactory = get('reference_factory'),
+                            valueFactory = get('value_factory');
+
+                        function AsyncOpcodeExecutor() {
+                        }
+
+                        util.inherits(AsyncOpcodeExecutor, OpcodeExecutor);
+
+                        AsyncOpcodeExecutor.prototype.execute = function (opcode) {
+                            var result = opcode.handle();
+
+                            if (!opcode.isTraced()) {
+                                // Don't attempt to make any untraced opcodes pause,
+                                // as resuming from inside them is not possible.
+                                return result;
+                            }
+
+                            if (result instanceof Value) {
+                                return valueFactory.createAsyncPresent(result);
+                            }
+
+                            if (result instanceof Reference || result instanceof Variable) {
+                                return referenceFactory.createAccessor(function () {
+                                    // Defer returning the value of the reference.
+                                    return valueFactory.createAsyncPresent(result.getValue());
+                                }, function (value) {
+                                    // Defer assignment in a microtask to test for async handling.
+                                    return valueFactory.createAsyncMicrotaskFuture(function (resolve, reject) {
+                                        result.setValue(value).next(resolve, reject);
+                                    });
+                                }, function (reference) {
+                                    return result.setReference(reference);
+                                });
+                            }
+
+                            return result;
+                        };
+
+                        return new AsyncOpcodeExecutor();
+                    }
+                };
+            }
+        ]
+    });
+
+    return {
+        asyncRuntime: asyncRuntime,
+        psyncRuntime: psyncRuntime,
+        syncRuntime: syncRuntime,
+
+        createAsyncEnvironment: function (options, addons) {
+            return asyncRuntime.createEnvironment(options, addons);
+        },
+
+        createAsyncRuntime: createAsyncRuntime,
+
+        createPsyncEnvironment: function (options, addons) {
+            return psyncRuntime.createEnvironment(options, addons);
+        },
+
+        createPsyncRuntime: createPsyncRuntime,
+
+        createSyncEnvironment: function (options, addons) {
+            return syncRuntime.createEnvironment(options, addons);
+        },
+
+        createSyncRuntime: createSyncRuntime,
+
+        /**
+         * Attempts to make this integration test slightly less brittle when future changes occur,
+         * by scrubbing out things that are out of our control and likely to change (such as line/column numbers
+         * of stack frames within Mocha) and performs source mapping of the stack frame file/line/column
+         *
+         * @param {string} stack
+         * @param {Function} module
+         * @return {Promise<string>}
+         */
+        normaliseStack: function (stack, module) {
+            var moduleData;
+
+            if (!moduleDataMap.has(module)) {
+                throw new Error(
+                    'Test harness error: module data map does not contain data for this module - ' +
+                    'did you forget to set options.sourceMap?'
+                );
+            }
+
+            moduleData = moduleDataMap.get(module);
+
+            return new SourceMapConsumer(moduleData.sourceMapGenerator/*, sourceMapUrl */)
+                .then(function (sourceMapConsumer) {
+                    stack = stack.replace(
+                        // Find stack frames for the transpiled PHP code - source maps would not be handled natively
+                        // even if we embedded them in the generated JS, so we need to perform manual mapping
+                        /\(eval at transpile \(.*\/test\/integration\/tools.js:\d+:\d+\), <anonymous>:(\d+):(\d+)\)/g,
+                        function (all, line, column) {
+                            var mappedPosition = sourceMapConsumer.originalPositionFor({
+                                // Note: These number casts are required, the source-map library
+                                //       will otherwise fail to resolve any mappings
+                                line: line - errorStackLineOffset,
+                                column: column * 1
+                            });
+
+                            if (mappedPosition.line === null && mappedPosition.column === null) {
+                                // Unless something has gone wrong, we should be able to map all generated JS frames back to PHP
+                                throw new Error('Stack line in evaluated PHP code could not be mapped back to PHP source');
+                            }
+
+                            return '(' + mappedPosition.source + ':' + mappedPosition.line + ':' + mappedPosition.column + ')';
+                        }
+                    );
+
+                    // Normalise Mocha frames
+                    stack = stack.replace(new RegExp('^(.*)' + escapeRegex(mochaPath) + '(.*:)\\d+:\\d+', 'gm'), '$1/path/to/mocha$2??:??');
+                    // Group Mocha frames (to allow for differences between versions)
+                    stack = stack.replace(/(?:(?:.*\/path\/to\/mocha.*)([\r\n]*))+/mg, '    at [Mocha internals]$1');
+
+                    // Normalise Node.js internal frames
+                    stack = stack.replace(/^(?:([^/(]+?\()([^/]+?)\.js|(.*?)(?:node:)?internal\/(.*?)(?:\.js)?):\d+:\d+/gm, '$1$3/path/to/internal/$2$4:??:??');
+                    // Group Node.js internal frames (to allow for differences between versions)
+                    stack = stack.replace(/(?:(?:.*\/path\/to\/internal.*)([\r\n]*))+/mg, '    at [Node.js internals]$1');
+
+                    // Normalise PHPCore frames
+                    stack = stack.replace(new RegExp(escapeRegex(phpCorePath), 'g'), '/path/to/phpcore');
+
+                    return stack;
+                });
+        },
+
+        asyncTranspile: function (path, php, options) {
+            return transpile(path, php, asyncRuntime, options);
+        },
+
+        psyncTranspile: function (path, php, options) {
+            return transpile(path, php, psyncRuntime, options);
+        },
+
+        syncTranspile: function (path, php, options) {
+            return transpile(path, php, syncRuntime, options);
+        },
+
+        transpile: function (runtime, path, php, options) {
+            return transpile(path, php, runtime, options);
+        }
+    };
+};