﻿/*
	© 2015-2016 FrankHB.

	This file is part of the YSLib project, and may only be used,
	modified, and distributed under the terms of the YSLib project
	license, LICENSE.TXT.  By continuing to use, modify, or distribute
	this file you indicate that you have read the license and
	understand and accept it fully.
*/

/*!	\file Test.txt
\ingroup Documentation
\brief 测试项目说明。
\version r269
\author FrankHB <frankhb1989@gmail.com>
\since build 597
\par 创建时间:
	2015-05-09 13:10:21 +0800
\par 修改时间:
	2016-06-11 01:20 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::Test
*/


/*

@0 体例和适用范围：
引用标记参见 [Documentation::CommonRules @@0.1] 。
项目范围参见 [Documentation::ProjectRules @@1] 。
本文档适用于项目中所有和测试相关的顶级子项目([Documentation::ProjectRules @@1.3])，包括示例项目。

@1 概述：

@1.1 测试范围：
预期涵盖版本库内所有顶级子项目。
实际只保证其中的一个较小的子集。

@1.2 测试策略：
因为变动较大，当前只对关键 API 进行覆盖，而不是全面覆盖。
当前测试覆盖以功能点(function point) 为基本单位，不考虑对变更实现较低效的行覆盖(line coverage) 和分支覆盖(branch converage) 。

@1.3 测试计划：
任意版本的日常发布应符合版本控制([Documentation::ProjectRules @@3.2]) 中对测试的要求。
除以下章节中的项目外，当前不考虑单独的其它测试计划。

@1.4 提交版本支持：
关于支持等级，参见 [Documentation::ProjectRules @@3.1.1.1] 。
关于构建的支持和依赖项历史，参见 [Documentation::Dependencies] 。
关于测试支持的环境，参见 @5 。
除非另行说明，以下每个平台包括 debug 和 release 配置，都为第一类支持。

@1.4.1 有限支持限制：
特定的平台配置对默认支持的策略按需进行修改。当前具有以下限制：
DS debug 配置限制，参见 @5.1.1.2 。

@1.4.2 正式支持([Documentation::ProjectRules @@2.1.1]) 历史：
项目起始添加 DS 平台第一类支持。
build 132 区分 DS 平台的 debug 和 release 配置的第一类支持。
build 299 添加 MinGW32 的 debug 和 release 配置的第一类支持。
build 300 降低 DS 平台的 debug 和 release 配置为第二类支持。
build 492 添加 Android 的 debug 和 release 配置的第二类待定支持。
build 598 降低 DS 平台的 debug 配置为第三类支持。

@1.4.3 非正式支持的平台配置：
以下平台不保证存在可通过可构建和正确性测试的配置，但不否定未来计划支持的可能性：
build 520 起 MinGW64 平台被保留平台标识符。
build 559 起 Linux 平台（未完整实现）被保留平台占位符。
build 561 起 OS X 平台（未完整实现）被保留平台占位符。
build 561 起 MSYS2 平台为区分 MinGW32 被保留平台占位符。

@1.4.4 最小构建数：
提交版本的最小构建数 X ([Documentation::ProjectRules @@3.2.1]) 和配置相关。
对现有配置， A(DS) = 4 ； A(MinGW32) = 3 ； A(Android) = 3 ； 所有 B(i) 默认为 2 （ debug 和 release 配置） 。因此 X = 12 。
因为 DS debug 的第一类支持被移除，自 b598 起 X = 11 。

@2 测试项目 Test ：
测试项目 Test 位于目录 /test ，依赖 YBase::Test 和 Tools::Scripts 的构建脚本。
测试项目的二进制兼容性保证为依赖被测试项目和 YBase 的二进制兼容性保证中较弱的一个。
当前仅支持 YBase 。
详见目录 /test 下的自述文件。

@3 计划 GUI 测试项目 ShlExplorer ：

@3.1 基本部件测试：
Label 、 Button 、 Window 等基本控件的静态显示。

@3.2 隐含部件测试（非单独测试，作为正常功能集成使用）：
Button 功能。
CheckBox 功能。
ListBox 功能（含 VerticalTrack 和 VerticalScrollBar 功能）。
FileBox 功能。
ProgressBar 功能。

@3.3 部件综合测试：
显示/隐藏控件。
顶层控件测试：菜单和子菜单测试。

@3.4 进阶互斥测试组：

@3.4.1 显示：
屏幕直接绘制。
动态 FPS 显示。

@3.4.2 屏幕接触移动：
边界测试：移动接触点记录 Enter 和 Leave 事件参数。
拖放测试：拖动控件（ Button 和 Window 等）。

@3.4.3 背景变换：
背景色变换。
背景图像替换。

@4 DS 测试项目 ShlReader ：
文本阅读器和十六进制阅读器。

@4.1 文本浏览：
支持 txt 、 c 、 cpp 、 ini 等后缀按文本打开。
使用随机载入复杂度为 O(1) 的算法，缓冲时间和文本文件大小无关。

@4.1.1 编码支持：
支持带 BOM 的 UTF-8 、 UCS-2LE 、 UCS-2BE 、 UCS-4LE 、 UCS-4BE 编码。
不带 BOM 的编码只读取文件起始字节（至多 64 个）判断为 UTF-8 或 GBK 。
按 GBK 打开时，可以顺序阅读，但不保证随机定位后读取的内容正常（GBK 无法保证随机定位时一定能选取到字符起始字节）。
模拟器上读取 GBK 编码文件极慢（可能需要等待数十秒），因为需要在二进制文件中载入编码表，属于正常情况。

@4.1.2 操作说明：
上下换行，左右翻页， LR 调整行距， XY 调整字体 。
Start （对 MinGW32 ，映射为 P 键）开启自动滚屏（可在设置界面配置以行为单位或以像素为单位平滑滚屏以及滚屏时间间隔），任意其它输入停止。
点击屏幕阅读区域显示/隐藏显示状态和详细功能按钮的阅读框。双击屏幕阅读区域开启自动滚屏。
点击阅读框中的进度随机定位。
点击 M 按钮打开菜单。
点击 S 按钮打开设置面板。
点击 I 按钮打开文件和阅读位置信息。
点击 B 按钮打开书签面板。焦点在书签列表框外时可以按键盘滚动并在上屏浏览文本。
点击 R 按钮返回。
点击 ←→ 按钮前进/后退（切换最近浏览位置）。
其它功能，如切换字体和背景颜色等，使用菜单（ M 按钮）选择“设置”进入详细设置界面自定义。
b429 起选择文件界面支持按组合键 L+R 或右下角按钮切换上下屏幕。

@4.1.3 设置和配置：

@4.1.3.1 build 345 起：
支持选择设置保存为配置项到配置文件。
打开 Shell 读取文件时自动载入配置，若不存在则追加配置并向配置文件写入。
仅当进入文本阅读器时读取配置文件；通过 GUI 中的菜单或按钮正常退出 Shell 时并写入配置文件。
生成的默认配置如下：
//[
(
	YReader
	(
		ReaderSetting
		(
			DownColor "192 216 240"
		)
		(
			FontColor "0 0 0"
		)
		(
			FontFamily "SimSun"
		)
		(
			FontSize "14"
		)
		(
			ScrollDuration "1000"
		)
		(
			SmoothScroll "1"
		)
		(
			SmoothScrollDuration "80"
		)
		(
			UpColor "240 216 192"
		)
	)
)
//]

@4.1.3.2 build 400 起：
追加书签读取和写入支持，保存至 YReader 下 Bookmarks 节点，形如：
Bookmarks
(
	"F:\Programing\NDS\YSTest\CC BY-SA 3.0 legalcode.txt" "173 743 0 3578 "
)
整数值表示在文件的字节位置。
空白符除了作为间隔以外会被忽略。以空白符分组后，非整数值起始的项时此项和之后所有项都会被删除。

@4.1.3.3 build 450 起：
增加 MIME 类型和文件扩展名映射配置文件，参见 @5.6.3 。
所有配置按 NPLA1 读取，共享实现。

@5 测试注记：
以下注记仅适用提交版本([Documentation::ProjectRules @@3.2.1.2]) ，对已提交的版本为测试记录，未提交的版本为测试计划。
示例测试项目 YSTest 包含 @3 和 @4 提到的测试。
测试使用的二进制文件构建方式和发布版本相同，参见 https://bitbucket.org/FrankHB/yslib/wiki/Run.zh-CN.md 。

@5.1 执行覆盖：
二进制相同的映像不重复测试。另见 [Documentation::Meta] $bin_image_eq 。
自 build 363 起关于界面包含编译时间（直至 build 564 被取消），因此原则上不会有相同的二进制文件。

@5.1.1 DS ：

@5.1.1.1 模拟环境测试：
测试环境 Windows PC （同 @5.1.2 ） + DeSmuME(x86/x64) 0.9.6 或以上（含 SVN 版本）：
所有 DS 的第一类支持的配置通过 PC 测试。

@5.1.1.2 debug 配置限制：
.nds 映像在装载到烧录卡时和程序的运行时共同使用 RAM 。
因为 .nds 映像二进制大小增加（约 2 MiB ）使运行时可使用的 RAM 受限（小于 2 MiB ）导致测试主要功能上的潜在困难， build 598 起的 debug 版本降为第三类支持。
事实上， build 527 起因为分配失败， debug 配置的程序已无法恢复切换 Shell 。

@5.1.1.3 实机测试：
以下版本（拟）通过 iDSL+DSTT 实机测试：
build 132 前的所有版本；
build 416 及之前的 DS 提交版本（除 build 387 rev 20[release] ） ；
build 428 之前的 DS release 提交版本。
build 428 - build 452 每 4 个 DS release 提交版本。
build 460 - build 500 每 20 个 DS release 提交版本。
build 600 起的发布版本。

@5.1.1.4 历史运行时环境配置注记：
本节包含历史环境配置，部分可能已不需要使用。
PreAlpha 1 ：目录 efsroot 用于存放外部文件（曾计划使用 EFS ，未实现），后作为运行时环境的外置存储的根目录。
其中 Font 目录下存放至少一个 TTF 字体文件。

@5.1.2 MinGW ：
所有 MinGW32 版本通过 64 位 PC 系统测试。
build 438 前及 build 497 - build 499 起测试环境 Windows 7 Ultimate 。
build 438 - build 452 测试环境 Windows 2012 Datacenter 。
build 453 - build 496 及 build 500 - build 648 测试环境 Windows 2012 R2 Datacenter 。
build 649 - build 650 Windows 10 Enterprise 。
build 651 起 Windows 10 Threshold 2 Professional 。

@5.1.3 Android ：
所有 Android 版本通过 PC 测试。测试环境 Windows x64 + Android 模拟器 Nexus S ，宿主操作系统版本同 MinGW 。

@5.1.4 非正式支持平台：
2013-02-13: Arch Linux x86_64 使用 wine-1.5.23 i386 (WOW64) 测试 MinGW32 平台版本 b346 、 b352 、 b360 、 b372 和 b379 可正常载入配置和退出，但打开文件时候程序失败。
2013-07-17: Chakra x86_64 使用 wine-1.5.31 i386 (WOW64) 测试 MinGW32 平台版本 b429 ，基本同上；性能明显降低（ debug 版本慢于 DS 版本）；覆盖配置会导致路径问题而不能再次启动（需要在 ":" 后补充 "\" ）；此外因为权限读写失败时程序错误退出，否则有可能成功。
2014-07-22(build 520) 起 MinGW64 提供第四类支持。
2014-12-20(build 561) 起 Linux 平台（未完整实现）可运行 stage 1 SHBuild ，提升为第四类支持。

*/
////

