add jtreg and jcstress README by luchang

41ea4698 · luchang · 0c60e3ae · 41ea4698
隐藏空白更改
内联并排

Showing with 213 addition and 0 deletion

jtreg+jcstress.md jtreg+jcstress.md +213 -0

未找到文件。
--- a/jtreg+jcstress.md
+++ b/jtreg+jcstress.md
+# Jcstress
+
+## Jcstress介绍
+
+Jcstress是openjdk开源的实验性测试套用于测试JVM并发能力的测试套
+
+Jcstress 获取地址：https://builds.shipilev.net/jcstress/jcstress-tests-all-20191016.jar
+
+## 执行jcstress
+
+java -jar jcstress.jar
+
+## 执行jcstress单个用例
+
+java -jar jcstress.jar -t testcase
+
+## 测试结果
+
+Jcstress的执行结果生成在results/index.html文件中
+
+# Jtreg
+
+## jtreg介绍
+
+jtreg是openJDK社区开放的测试框架，提供公共配置和方法以便社区开发者进行测试代码的编写和执行
+
+jtreg 获取地址：https://ci.adoptopenjdk.net/view/Dependencies/job/jtreg/lastSuccessfulBuild/artifact/jtreg-4.2.0-tip.tar.gz
+
+## 开源测试套
+
+OpenJDK 8 开源测试套：`hg clone http://hg.openjdk.java.net/jdk8u/jdk8u/`
+
+下载openjdk开源代码之后，运行bash get_source.sh 下载测试套。
+
+OpenJDK 11 开源测试套：`hg clone http://hg.openjdk.java.net/jdk-updates/jdk11u`
+
+JDK11源代码clone下载之后测试用例在test目录下。
+
+## 执行开源测试用例
+
+1. 设置环境变量  
+`export JAVA_HOME=path/to/JDK`  
+`export PATH=$JAVA_HOME/bin:$PATH`  
+`export JT_HOME=path/to/jtreg_home`  
+`export PATH=$JT_HOME/bin:$PATH`  
+2. 执行测试用例   
+   2.1 执行单个用例
+       `jtreg -va XXX/YYY.java`
+   2.2 执行整个测试套
+   ```
+       jdk8u:
+       jtreg -va -ignore:quiet -jit -conc:auto -timeout:5 -tl:3590 -exclude:exclude.txt -vmoptions:"$jvmOptions" jdk8u/hotspot/test jdk8u/langtools/test jdk8u/nashorn/test jdk8u/jdk/test
+       jdk11u:
+       jtreg -va -ignore:quiet -jit -conc:auto -timeout:5 -tl:3590 -exclude:exclude.txt -vmoptions:"$jvmOptions" jdk11u/test/
+   ```
+3. 查看执行结果   
+    测试套的结果统计在JTreport/html/report.html中   
+    测试用例的日志存放在Jtwork中，用例XXX/YYY/ZZZ.java的执行日志存在在JTwork/XXX/YYY/ZZZ.jtr文件中   
+    jtr文件中test result有三种状态：Passed、Failed、Error，分别对应用例执行通过，执行失败和执行出错。
+
+## jtreg使用说明
+
+用户对jtreg框架的使用是通过执行封装好的jtreg脚本来实现。jtreg的接口详细说明如下：
+
+- 参数说明：
+```
+\-v:<value> : 测试环境配置
+-v1                                       输出一行测试用例名称、状态
+-va                                       输出所有用例全部输出
+-ve                                       输出error用例的全部信息
+-vf                                       输出fail用例的全部信息
+-vp                                       输出pass用例的全部信息
+-vt                                       输出每个步骤的具体时间
+-conc：<factor>                           用例并发数，auto=空闲的核数
+-e:name[=value][,name[=value]...]         指定测试用例的环境变量
+-ignore：< quiet | error | run >;         添加ignore标签的用例的处理方法
+-l：                                      列出所有测试用例
+-nr:                                      不生成report
+-r: <directory>                           存放report的目录，默认为JTreport
+-timeout:<factor>                         用例超时限制，输入为120s的吧倍数。
+                                                eg. -timeout:5 = 600s
+-tl:<#second>                             对于超时时间超过这个参数的用例，不执行
+-w:<directory>                            指定工作目录，默认为JTwork
+-a                                        带有/manual标签的用例都不会执行。
+-exclude:<file>                           文件中的用例会被过滤
+-m                                        仅运行带/manual的用例
+-noshell                                  过滤掉任何需要执行shell脚本的用例
+-shell                                    仅执行shell脚本用例
+-agentlib:<libname>[=<options>]           加载本地库
+-agentpath:<pathname>[=<options>]         根据本地库的完整路径加载本地库
+-compilejdk:<java.home>                   使用指定的JDK编译用例
+-D<name>=<value>                          定义一个系统属性  
+-javacoptions:<option>...                 编译时额外的javac 选项
+-javaoptions:<option>...                  运行时额外的java 选项
+-jdk:<java.home>                          使用指定的jdk运行用例
+-jit                                      执行用例时开启jit
+-nojit                                    执行用例时关闭jit
+-vmoptions:<option>...                    编译和运行用例时额外的JVM选项
+-Xint | -Xmixed | -Xcomp                  JVM运行模式
+-help[words...]                           打印帮助页
+```
+
+- 使用示例
+  - 执行目录下所有用例  
+  `jtreg xxx/yyy`
+  - 执行用例并打印所有日志  
+  `jtreg -va xxx/yyy`
+  - 并发执行用例  
+  `jtreg -va -conc:48 xxx/yyy`
+  - 使用执行JDK和JVM参数执行用例  
+  `jtreg -jdk:$JAVA_HOME -vmoptions:"-Xmx2g -Xms2g" -va -conc:48 xxx/yyy`
+  - 过滤掉ignore用例与过滤列表用例  
+  `jtreg -jdk:$JAVA_HOME -vmoptions:"-Xmx2g -Xms2g" -va -conc:48 -ignore:quiet -exclude:exclude/file.txt xxx/yyy`
+
+- 使用说明
+  - 测试用例的某一级上层目录中必须包含TEST.ROOT文件，其中可以描述测试套配置，也可以为空
+  - 测试用例中必须带有jtreg能够识别的注释头，框架才能识别测试用例
+  - 需要使用JDK1.7以上版本运行jtreg
+  - 可以使用jtreg.jar或bin目录下封装好的jtreg脚本执行框架
+
+
+- 框架目录
+[待补充]
+
+## jtreg用例注释参数说明
+```
+  /*
+   * @test                                声明此文件为一个测试用例
+   * @summary                             此用例的描述
+   * @author                              用例作者
+   * @requires                            用例执行的前置条件 eg. @requires "os.maxMemory > 32g"
+   * @modules                             描述用例依赖的模块
+   * @library                             用例所需库文件的地址或jar文件，以/开始的路径意味着相对于TEST.ROOT所在目录的路径，否
+                                          则意味着相对于测试用例所在目录的路径。以${java.hone}开头的路径意味被测JDK中的库文件
+   * @run <type><option>*<arg>*           执行用例的类型与选项、参数
+                                          <type>描述执行用例的类型， <option>描述如何执行用例，<arg>描述执行用例时的参数。
+     eg.@run build <classname-or-wildcard>+           编译class文件
+        @run clean <classname-or-wildcard>+           移除class文件
+        @run compile[/fail][/ref=<file>]              编译class文件，timeout选项定义了整个compile过程的超时时间，module选项用于
+         [/timeout=<seconds>][/process]               编译一个maodule，fail选项代表此编译过程预期失败
+         [/module=<module-name>] <arg>+
+        @run main[/fail][/manual][/othervm]           执行指定class的main函数，fail选项代表此编译过程预期失败，manual选项的用例
+         [/policy=<file>][/secure=<class>]            全量执行的时候不会执行，othervm强制用例使用新的VM，policy定义系统属性java.
+         [/timeout=<seconds>] <vm-opt>*               security.policy,secure指定security manager，timeout定义执行过程的超时时间
+         <class> <arg>*
+        @driver[/fail][/timeout=<seconds>]            与run type相似，driver执行的用例不会继承jtreg的参数，适用于执行测试前需要
+         <class> <arg>*                               重新配置环境的场景
+        @junit[/fail][/manual][/othervm]              与run type相似，运行junit用例
+         [/policy=<file>][/secure=<class>]
+         [/timeout=<seconds>] <vm-opt>* <class>
+        @testng[/fail][/manual][/othervm]             与run type相似，运行testng用例
+         [/policy=<file>][/secure=<class>]
+         [/timeout=<seconds>] <vm-opt>* <class>
+        @applet[/fail][/manual[=(yesno|done)]]        运行java applet用例    
+         [/othervm][/policy=<file>]
+         [/secure=<class>][/timeout=<sec>]
+         <html-file>
+        @shell[/fail][/manual][/timeout=<seconds>]    运行shell用例
+         <script> <arg>*
+        @ignore <word>*                               标注了ignore的用例根据-ignore:<run|quiet|error>选项觉定是否运行
+   */
+```
+<font color="#660000">PS: 推荐按照以上顺序排列tag</font>
+
+## @requires标签中的关键字
+
+|  关键字   | 描述  | 值 |
+|  ----  | ----  | --- |
+|  jdk.version | JDK版本，与系统属性 java.specification.version 相同 |  |
+|  os.name | 操作系统名称 |  |
+|  os.family | 操作系统 | linux/mac/solaris/windows |
+|  os.arch | 操作系统架构 |  |
+|  os.simpleArch | 简化操作系统架构 | x64 / i586 |
+|  os.version | 操作系统版本 |  |
+|  os.simpleVersion | 简化操作系统版本 | 操作系统版本的前两位 |
+|  os.processors | 系统核数 | Runtime::availableProcessors |
+|  os.maxMemory | 系统最大内存 | OperatingSystemMXBean::getTotalPhysicalMemorySize |
+|  os.maxSwap | 系统最大交换分区 | OperatingSystemMXBean::getTotalSwapSpaceSize |
+|  vm.gc | 垃圾回收策略 | name |
+|  vm.opt.switch | 布尔型JVM选项 -XX:+/-switch| true / false |
+|  vm.opt.name | VM选项 -XX:name=value | value |
+
+
+
+## 框架使用的环境系统属性与环境变量
+
+|  系统属性   | 环境变量  | 描述 |
+|  ----  | ----  | --- |
+| test.file | TESTFILE	 | 用例文件 |
+| test.src | TESTSRC | 用例所在目录 |
+| test.src.path | TESTSRCPATH | 库文件目录 |
+| test.classes	 | TESTCLASSES | 编译后的class文件所在目录 |
+| test.class.path	 | TESTCLASSPATH | 用例所有class文件所在目录 |
+| test.vm.opts	 | TESTVMOPTS | 执行用例的JVM选项 |
+| test.tool.vm.opts	 | TESTTOOLVMOPTS | JVM工具的选项，以-J开头 |
+| test.compiler.opts	 | TESTJAVACOPTS | javac选项 |
+| test.java.opts	 | TESTJAVAOPTS  | 执行java时的选项 |
+| test.jdk	 | TESTJAVA | 被测试JDK |
+| compile.jdk	 | COMPILEJAVA | 用于编译的JDK |
+| test.timeout.factor	 | TESTTIMEOUTFACTOR | 超时参数 |
+| test.nativepath	 | TESTNATIVEPATH | 本地可执行文件目录 |
+| test.modules	 | TESTMODULES | 用例所依赖的模块 |
+| test.root	 | TESTROOT | TEST.ROOT所在目录 |
+| NA | FS | 文件分隔符(windows下为\ 其他系统为/) |
+| NA | PS | 地址分隔符（windows下为; 其他系统为:） |
+
+## Jtreg的日志说明
+
+所有用例执行结束之后
+
+- 执行日志将存放在JTwork目录下的.jtr文件中
+- 统计结果将存放在JTreport目录下的.html文件中
+- JTreport 和 JTwork文件夹将在用例执行完成后生成