karate-js 深度解析：Karate 项目自研的轻量级 JVM 纯 Java JavaScript 引擎

测试接口测试性能测试Mock【免费下载链接】karateTest Automation Made Simple项目地址https://gitcode.com/gh_mirrors/ka/karate点击查看免费下载导读本文以仓库内 karate-js/README.md 为主体骨架结合 docs/JS_ENGINE.md、docs/DESIGN.md 设计文档与 Engine.java 等源码实现系统讲解 karate-js 的定位、架构、线程模型、Java/JS 互操作方式与独立集成方法。读完本文你将掌握如何在自己的 JVM 项目中用几行 Java 代码嵌入一个无 GraalVM 依赖、线程安全的 ES6 兼容 JavaScript 引擎并理解其类型系统与并发设计的底层原理。什么是 karate-jskarate-js 是 Karate 自动化测试框架项目描述 Test Automation Made Simple中一个从零实现implemented in Java from scratch的轻量级 JavaScript 引擎。它运行在 JVM 上核心设计目标有三线程安全完整支持跨线程的并发执行Java 互操作在 Java 与 JS 代码之间架起双向桥梁可从 Java 侧对引擎进行全面控制、行为定制与内省最小化JAR 体积小运行时依赖极少——按 README 声明SLF4J 与 JSON-smart 是其仅有的两个依赖项且不依赖 GraalVM见 docs/JS_ENGINE.md 的 Overview。在 Karate v2 的整体架构中karate-js 处于地基位置。根据 docs/DESIGN.md 的模块地图karate/ ├── karate-js/ # JS engine reusable parser framework Resource abstraction │ ├── io.karatelabs.js # Engine, Context, Bindings, JsValue hierarchy │ ├── io.karatelabs.parser # BaseParser, BaseLexer — extended by GherkinParser │ └── io.karatelabs.common # Resource, Pair, StringUtils (no karate-core deps) ├── karate-core/ # Runtime, HTTP, matching, mocks, reports, templating, gherkin model └── ...karate-core 中的KarateJs类JS 引擎桥接层承载karate.*API即构建在 karate-js 之上同时 karate-js 提供的解析器框架io.karatelabs.parserBaseParser、BaseLexer还被 karate-core 的GherkinParser继承复用。这意味着 karate-js 不仅是测试脚本执行器更是一套可独立复用的解析 执行基础设施。核心特性一览README 将 karate-js 的特性归纳为五点本文结合源码逐一展开特性含义源码佐证Thread-safe完整支持跨线程并发执行引擎实例互不污染Engine.java 的jsLock与 per-Engine 状态隔离EngineConcurrencyTest.javaMinimalJAR 体积小仅 SLF4J JSON-smart 两个依赖README 声明karate-js 的 pom.xml 本身不引入运行时框架Java Interop双向桥接 Java 与 JS支持行为定制与内省JsJavaInteropTest.java、JsValue密封类型层次Simple代码库精简配有大量单元测试仓库中karate-js/src/test/java/io/karatelabs/js/下 40 个测试类Fast以性能优先为设计原则README 提及独立基准仓库JS_ENGINE.md 的 Design Principles常规路径下基本类型保持 Java 原生类型需要说明的是karate-js 的目标是覆盖现实世界中最常用的惯用 ES6idiomatic ES6部分高级特性被有意地不支持——这一点在 docs/JS_ENGINE.md 中有详尽的已知偏离known deviations清单下文设计取舍小节会展开。架构三大包的清晰分工karate-js 模块内部按职责分为三个包README 给出了简明表格包职责io.karatelabs.js核心 JavaScript 引擎解释器Interpreter、运行时CoreContext、ContextRoot、内建类型JsNumber、JsArray、JsPromise等完整JsValue层次io.karatelabs.parser解析基础设施词法分析器JsLexer、BaseLexer、语法分析器JsParser、BaseParser、AST 节点Node、NodeType与 karate-core 共享io.karatelabs.common通用工具文件FileUtils、PathResource、UrlResource、MemoryResource、OSOsUtils、字符串StringUtils等不依赖 karate-core三个包的依赖方向是单向的common不依赖jsjs依赖parser整模块不依赖 karate-core——这正是它能被第三方独立使用的前提。从源码看一次 eval 的完整调用链以 Engine.java 的eval(String text)入口为例L323-L325evalInternal首先调用checkPoisoned()做引擎健康检查——如果引擎已因异步任务超时被毒化poisoned后续 eval 会快速失败而非阻塞在可能被卡住的锁上L481-L493enterEvalScope()打开或共享一个异步作用域最外层 eval 被串行化第二个宿主线程会阻塞直到当前作用域彻底关闭L248-L277通过JsParser把源码解析为 ASTNoderunLocked()在公平的ReentrantLockjsLock保护下执行加锁 → 通过Engine.enter(this)把当前引擎写入线程本地CURRENT供 JVM 级原型单例解析 per-Engine 可变状态→Interpreter.eval(program, context)→ 释放并恢复L456-L474最外层 eval 结束后AsyncSupport.finishScope排空所有异步任务至静默quiescence结果经toJava()转成 Java 侧的类型返回L495-L510。快速上手三个 eval 示例README 给出的最小用法非常直接——新建一个Engine实例即可求值任意 JS 表达式import io.karatelabs.js.Engine; Engine engine new Engine(); Object result engine.eval(1 2); // result 3Engine还重载了多种求值入口均返回String → value的同步契约从源码看见 Engine.javaeval(String text)求值一段 JS 源码文本eval(File file)/eval(Resource resource)求值文件或资源io.karatelabs.common.Resource抽象支持路径、URL、内存文本等来源见PathResource、UrlResource、MemoryResourceevalWith(String text, MapString, Object vars)带局部变量求值static parse(String text)只解析不执行返回 ASTNode供 linter、格式化器等工具使用。注入宿主变量Java Interop 的入门形态README 展示了通过putAll把 Java 侧数据注入 JS 作用域的经典模式MapString, Object context new HashMap(); context.put(greeting, Hello); Engine engine new Engine(); engine.putAll(context); Object result engine.eval(greeting World); // result Hello World从源码看Engine.put(String name, Object value)直接把值写入引擎唯一的绑定存储BindingsStoreEngine.javaputAll即批量写入。与绑定相关的完整 API 还包括get(String name)/remove(String name)读取自动解包或删除绑定getBindings()返回用户可见绑定的自动解包视图JsDate → Date、undefined → null隐藏条目内置惰性缓存、putRootBinding注入的资源会被过滤getRootBindings()返回隐藏的根绑定——karate-core 的ScenarioRuntime用它把隐藏状态继承进被 call 的 feature见 Engine.java。深入 Java Interop类型系统与双向转换karate-js 的互操作能力建立在一套精心设计的类型系统之上这是它区别于能用就行的脚本引擎的关键。密封的 JsValue 层次引擎对需要做 Java 互操作转换的 JS 包装类型定义了一个密封接口层次docs/JS_ENGINE.md 的 Type System 一节public sealed interface JsValue permits JsUndefined, JsPrimitive, JsDateValue, JsBinaryValue { Object getJavaValue(); // 对外供 Java 消费如 JsDate → Date default Object getJsValue() { return getJavaValue(); } // 对内供引擎运算如 JsDate → double timeValue } sealed interface JsPrimitive extends JsValue permits JsNumber, JsString, JsBoolean, JsBigInt {} sealed interface JsDateValue extends JsValue permits JsDate {} sealed interface JsBinaryValue extends JsValue permits JsUint8Array {}核心设计原则是内部表示与外部表示分离Design Principles 第 2 条JS 内部保持原始语义undefined、原型链、JsDateJava 侧通过getJavaValue()拿到惯用的 Java 类型。类型映射表JS 类型Java 包装类getJavaValue()返回层次undefinedJsUndefinednullJsValueNumberJsNumberNumberJsPrimitive → JsValueStringJsStringStringJsPrimitive → JsValueBooleanJsBooleanBooleanJsPrimitive → JsValueBigIntJsBigIntBigIntegerJsPrimitive → JsValueDateJsDateDateJsDateValue → JsValueRegExpJsRegexPattern—ArrayJsArrayListObject—ObjectJsObjectMapString, Object—MapJsMapMapextendsJsObjectSetJsSetSetextendsJsObjectUint8ArrayJsUint8Arraybyte[]JsBinaryValue → JsValue值得注意的细节Javabyte[]进入 JS 时被特殊处理为JsUint8Array二进制而不是降级成ListByte因此 Java 方法返回的byte[]在跨边界往返后仍能还原为byte[]——该规则在所有入站路径上生效字面量/值转换与反射方法返回并由ExternalBridgeTest锁定Base64.decode(...) → byte[]、DemoPojo.bytes() → byte[]可在 JS 中以Uint8Array的.length/索引访问。惰性转换与双通道访问类型转换发生在使用点而非构造时。两个关键实现点1. 惰性入站转换Terms.toJavaMirror()对String、Number、Boolean、java.util.Date、Instant、LocalDateTime、LocalDate、ZonedDateTime、byte[]等输入按需包装成JsString、JsNumber、JsDate、JsUint8Array。惰性的理由引擎绑定可能被外部线程更新线程安全、单一转换点覆盖所有入口简洁、instanceof链开销可忽略性能。2. 集合的双通道访问JsArray implements ListObject、JsObject implements MapString, Object但同一个对象对两种消费者呈现不同视图访问模式方法返回值适用方Java 接口List.get(int)/Map.get(Object)自动解包undefined→null、JsDate→DateJava 消费者JS 内部getElement(int)/getMember(String)原始值undefined、JsDate引擎内部例如engine.eval([1, undefined, new Date(0)])后以List视角读取得到[1, null, Date]以JsArray视角getElement则得到[1, Terms.UNDEFINED, JsDate]。这种延迟自动解包避免了toList()/toMap()的复制开销且让 JS 代码在引擎内部始终看到原生语义。JsJavaInteropTest对这些行为做了系统验证例如testJsArrayIsInstanceOfList断言JsArray是List的实例、testTopLevelJsDateBecomesDate断言顶层new Date(86400000)返回java.util.DateJsJavaInteropTest.java。单例原型系统与 per-Engine 隔离方法继承采用 JavaScript 标准的原型链但内建原型是JVM 级共享单例JsArrayPrototype.INSTANCE ← JsObjectPrototype.INSTANCE ← null等其可变状态全部放在 per-Engine 的覆盖层overlay中通过Engine.current()eval 作用域的 ThreadLocal解析。这意味着内存高效每种类型只有一个原型实例规范合规Array.prototype.foo ...这类 polyfill 模式可用引擎隔离一个引擎里Map.prototype.set function(){ throw ... }既不会污染其他引擎也不会被其他引擎的清理逻辑误删——并发引擎之间完全隔离无需重置步骤。EngineConcurrencyTest专门钉死了这个契约8 个线程各自反复新建Engine并执行Object.keys/Array.isArray脚本历史上并发套件跑会出现 Object.keys is not a function 的间歇性失败即源于此问题测试断言所有线程零失败EngineConcurrencyTest.java。线程安全模型jsLock 与异步作用域README 把Thread-safe列为首要特性其实现并非简单的互斥而是一套在 docs/JS_ENGINE.md 中被严格定义为铁律Iron rules的并发模型JS 只在Engine.jsLock下执行jsLock是一个公平的ReentrantLock保证任何时刻恰好一个线程运行 JS解释器内部没有其他同步原语每个加锁区间都会建立并恢复Engine.current()。外部线程永不执行 JS、永不触碰JsObject状态定时器线程、互操作执行器等只能完成CompletableFuture、入队任务并唤醒线程JS 状态变更一律回到队列中排队执行。静默quiescence计量是线性化的每单位在途工作持有一个AsyncToken后继工作总是在释放其令牌之前入队因此外部线程永远无法向已关闭的作用域发布任务。这一模型同时支撑了async/await/Promise虚拟线程激活 per-Engine 锁、setTimeout/clearTimeout共享惰性单线程调度器有意不实现setInterval因为它永远无法静默以及生成器function*/yield每个已启动的生成器独占一个虚拟线程与其驱动线程在公平锁下严格交替。对使用者而言需要记住的实践要点一个Engine实例同一时刻本质上是单线程执行 JS 的但多个Engine实例可以安全地在多个线程并行运行——karate-core 并行套件中每个场景一个全新 Engine的模式EngineConcurrencyTest注释中明确说明就是这一能力的直接受益者宿主可通过Thread.interrupt()或Future.cancel(true)协作式终止长跑脚本EngineInterruptedExceptionJS 的try/catch无法吞掉它若异步销毁超时引擎会进入不可逆的毒化状态嵌入方不得把毒化的引擎归还复用池Engine.isPoisoned()可查询。独立集成在自有项目中使用 karate-jsREADME 明确说明本模块可独立于 karate-core 使用并给出了 Maven 坐标dependency groupIdio.karatelabs/groupId artifactIdkarate-js/artifactId version2.1.3.RC1/version /dependency说明上例版本取自当前仓库 karate-js/pom.xml其 parentkarate-parent的版本为 2.1.3.RC1README 中示例写作 2.0.0.RC1实际使用时应以你构建时对应的发布版本为准。由于io.karatelabs.js/io.karatelabs.parser/io.karatelabs.common三个包均不依赖 karate-core你可以将 karate-js 当作一个通用的 JVM 内嵌脚本引擎做 API 测试的断言计算、数据变换、规则引擎的脚本化、甚至仅复用其解析器/词法器基础设施。README 也欢迎贡献者持续改善 karate-js 的第三方解耦度Contributions that improve decoupling for third-party usage are welcome。测试与验证体系Simple - 代码库简洁、测试充足不是一句空话。karate-js的测试布局karate-js/src/test/java/io/karatelabs/js/覆盖了引擎的每个侧面也是深入理解引擎行为的入口关注点代表性测试引擎集成面EngineTestContextListener 事件、BindEvent、put生命周期、Java↔JS 异常边界语言语义EvalTest、JsClassTest100 用例含 ES2022 私有元素与箭头字段、JsGeneratorTest异步JsAsyncAwaitTest19 例、JsPromiseTest60 例、JsAsyncConcurrencyTest18 个屏障用例并发EngineConcurrencyTest多线程引擎隔离互操作JsJavaInteropTest1004 行、ExternalBridgeTest、HostCallThrowTest内建类型JsArrayTest、JsStringTest、JsObjectTest、JsDateTest、JsRegexTest、JsBigIntTest、JsMapSetTest、JsWeakMapSetTest等解析器JsLexerTest、JsParserTest、ParserExceptionTest、TokenCacheTest性能回归EngineBenchmark、RealisticBenchmark、LexerBenchmark、NodeSizeAnalysis此外仓库还包含独立的karate-js-test262模块用于按 ECMAScript 官方测试套件 test262 做规范一致性回归见 karate-js-test262/TEST262.md其expectations.yaml记录着当前已知偏离项。设计取舍有意不支持的 ES6 特性正如 README 所说some advanced features are intentionally not supported以下是 docs/JS_ENGINE.md 中明确列出的、有意的已知偏离挑选影响面较大的无setInterval、无queueMicrotask、无异步迭代器for await在解析期即被拒绝——因为它们要么无法静默、要么超出目标范围全局对象缺少Proxy、ArrayBuffer、DataView、WeakMap/WeakSetUint8Array是唯一的二进制类型Symbol是精简实现无Symbol.prototype、无注册表Symbol.for/keyFor、无description访问器well-known symbol 以内部字符串键如iterator参与迭代/ToPrimitive分发Reflect只有construct、apply、ownKeys缺get/set/has/deleteProperty类语义无super()前的this-TDZ、无super()返回值覆盖、内建异质类Error/Array的extends使用拷贝自有属性的 shim 而非真正的异质子类化装饰器与 public-field 一致性边缘用例保持 test262 跳过。这些取舍在 docs/JS_ENGINE.md 中有逐条的位置标注对应源码与测试是评估我的脚本能不能跑的第一手依据。许可karate-js 模块遵循 MIT License与整个 Karate 仓库一致允许自由使用、修改与再分发。延伸阅读均在当前仓库内引擎完整参考docs/JS_ENGINE.md类型系统、原型机制、异常处理、async/generator 的规范不变量项目总设计docs/DESIGN.md模块地图、线程与生命周期约定、ThreadUtils、KarateLifecycle引擎入口实现Engine.java并发契约测试EngineConcurrencyTest.java互操作契约测试JsJavaInteropTest.java规范一致性karate-js-test262/TEST262.md赞分享测试接口测试性能测试Mock【免费下载链接】karateTest Automation Made Simple项目地址https://gitcode.com/gh_mirrors/ka/karate点击查看免费下载相关推荐MediaPipe 完整指南5 分钟跑通人脸检测、手部追踪与实时姿态跟踪MediaPipe 完整指南5 分钟跑通人脸检测、手部追踪与实时姿态跟踪 视频里加一个虚拟背景、健身 App 里自动数一组深蹲背后往往是同一套代码。Medi测试接口测试性能测试MockKarate测试框架演示项目深度解析Karate测试框架演示项目深度解析 项目概述 Karate演示项目是一个精心设计的示例集合展示了Karate测试框架的各种核心功能和最佳实践。该项目基于Sp测试接口测试性能测试MockQuickJS引擎深度解析轻量级JavaScript运行时的革命QuickJS引擎深度解析轻量级JavaScript运行时的革命 你是否还在为嵌入式设备中JavaScript运行时的体积和性能问题烦恼是否在寻找一个既能满语言运行时解释器编程语言上一篇mcp-sequential-thinking构建结构化思维流程的终极指南下一篇Obsidian CardBoard重新定义你的任务管理体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考