solidproject/conformance-test-harness

Conformance Test Harness (CTH) Docker镜像文档

镜像概述和主要用途

Conformance Test Harness (CTH) Docker镜像用于运行针对Solid规范的一致性测试，验证Solid服务器实现是否符合标准。镜像内置最新测试用例、清单文件和测试主题配置，用户只需提供环境配置和目标服务器信息即可执行测试，生成覆盖度和结果报告。

核心功能和特性

• Solid规范测试：验证服务器对Solid协议、Web访问控制(WAC)等规范的实现
• 多源配置机制：支持Turtle测试主题描述、YAML配置文件、环境变量和命令行参数
• 灵活认证方式：支持客户端凭证、刷新令牌、会话登录和本地用户注册四种认证模式
• 并行测试执行：可配置线程数，支持并行运行测试用例，提高效率
• 详细报告生成：输出HTML+RDFa格式的覆盖度和结果报告，以及Turtle格式的机器可读结果

使用场景和适用范围

• Solid服务器开发者验证其实现是否符合规范
• CI/CD流程中集成自动化一致性测试
• 第三方评估Solid服务器兼容性
• 规范演进过程中的回归测试

前提条件

用户账户

需创建两个测试用户账户（alice和bob），可注册在任何兼容的Solid身份提供商(IdP)或被测服务器上。

测试容器

被测服务器需托管一个测试容器，alice用户必须对该容器拥有完全控制权（通过所有权或访问授权）。

配置说明

CTH依赖四种配置来源（按动态性从低到高排序）：

1. 测试主题描述

Turtle格式文件，使用EARL和DOAP词汇表描述测试对象及其能力。示例：

turtle
<css>
    a earl:Software, earl:TestSubject ;
    doap:name "Community Solid Server" ;
    doap:release <css#test-subject-release> ;
    doap:developer <https://github.com/solid> ;
    doap:homepage <https://github.com/solid/community-server> ;
    doap:description "An open and modular implementation of the Solid specifications."@en ;
    doap:programming-language "TypeScript" ;
    solid-test:skip "acp" ;
    rdfs:comment "Comment on the test subject"@en.
    
<css#test-subject-release>
    doap:revision "0.9.0" ;
    doap:created "2021-05-04T00:00:00.000Z"^^xsd:dateTime .

内置测试主题包括：

• <css>: Community Solid Server
• <ess>: Enterprise Solid Server
• <nss>: Node Solid Server
• <trinpod>: TrinPod

2. CTH配置文件

YAML格式，路径为config/application.yaml，用于覆盖默认设置。默认配置包含在Docker镜像中，示例：

yaml
subjects: test-subjects.ttl
sources:
  - https://solidproject.org/ED/protocol
  - https://github.com/solid-contrib/specification-tests/blob/main/protocol/solid-protocol-test-manifest.ttl
  - https://github.com/solid-contrib/specification-tests/blob/main/protocol/requirement-comments.ttl
  - https://solidproject.org/TR/wac
  - https://github.com/solid-contrib/specification-tests/blob/main/web-access-control/web-access-control-test-manifest.ttl

target: https://github.com/solid-contrib/conformance-test-harness/ess

mappings:
  - prefix: https://github.com/solid-contrib/specification-tests/blob/main
    path: ./data

agent: Solid-Conformance-Test-Suite
connectTimeout: 5000
readTimeout: 5000
maxThreads: 8
origin: https://tester

3. 环境变量

通过.env文件提供，包含核心配置、认证详情、日志和其他设置。

核心配置

shell
# 用户WebID
USERS_ALICE_WEBID=
USERS_BOB_WEBID=
# 身份提供商（可选）
SOLID_IDENTITY_PROVIDER=
# 测试容器路径（相对或绝对URL）
TEST_CONTAINER=
# 资源服务器根路径（可选，用于兼容旧配置）
RESOURCE_SERVER_ROOT=

认证方式

1. 客户端凭证

shell
USERS_ALICE_CLIENTID=
USERS_ALICE_CLIENTSECRET=
USERS_ALICE_IDP=
USERS_BOB_CLIENTID=
USERS_BOB_CLIENTSECRET=
USERS_BOB_IDP=

2. 刷新令牌

shell
USERS_ALICE_REFRESHTOKEN=
USERS_ALICE_CLIENTID=
USERS_ALICE_CLIENTSECRET=
USERS_ALICE_IDP=
USERS_BOB_REFRESHTOKEN=
USERS_BOB_CLIENTID=
USERS_BOB_CLIENTSECRET=
USERS_BOB_IDP=

3. 会话登录

shell
LOGIN_ENDPOINT=
USERS_ALICE_USERNAME=
USERS_ALICE_PASSWORD=
USERS_ALICE_IDP=
USERS_BOB_USERNAME=
USERS_BOB_PASSWORD=
USERS_BOB_IDP=
ORIGIN=

4. 本地用户注册

shell
USER_REGISTRATION_ENDPOINT=
USERS_ALICE_USERNAME=
USERS_ALICE_PASSWORD=
USERS_ALICE_IDP=
USERS_BOB_USERNAME=
USERS_BOB_PASSWORD=
USERS_BOB_IDP=
ORIGIN=

日志配置

shell
# 启用HTTP交互日志
quarkus.log.category."com.intuit.karate".level=DEBUG
quarkus.log.category."org.solid.testharness.http.Client".level=DEBUG
quarkus.log.category."org.solid.testharness.http.AuthManager".level=DEBUG
# JSON格式日志
QUARKUS_LOG_JSON_CONSOLE_ENABLE=true

其他配置

shell
# 并行测试线程数
MAXTHREADS=2
# 允许自签名证书
ALLOW_SELF_SIGNED_CERTS=true
# 已知失败测试列表路径
TOLERABLEFAILURES=filepath.txt

4. 命令行选项

usage: run
    --coverage                   仅生成覆盖度报告
 -f,--filter <arg>               功能过滤器
 -h,--help                       显示帮助信息
    --ignore-failures            即使有失败也返回成功
 -o,--output <arg>               输出目录
 -s,--source <arg>               测试源URL或路径
    --skip-reports               跳过报告生成
    --skip-teardown              跳过清理步骤
    --status <arg>               要运行的测试状态
    --subjects <arg>             测试主题配置文件（Turtle）URL或路径
 -t,--target <arg>               目标服务器
    --tolerable-failures <arg>   已知失败测试列表路径

执行步骤

Docker镜像结构

• /app/harness: 可执行JAR文件
• /app/config: 默认application.yaml配置
• /data: specification-tests仓库内容
• /reports: 报告输出目录

基本执行示例

1. 创建.env文件（以ESS为例）：

shell
quarkus.log.category."com.intuit.karate".level=DEBUG

SOLID_IDENTITY_PROVIDER=https://server/idp/
USERS_ALICE_WEBID=https://server/alice/profile/card#me
USERS_ALICE_USERNAME=alice@example.org
USERS_ALICE_PASSWORD=securepassword
USERS_BOB_WEBID=https://server/bob/profile/card#me
USERS_BOB_USERNAME=bob@example.org
USERS_BOB_PASSWORD=securepassword
USER_REGISTRATION_ENDPOINT=https://server/idp/register/

RESOURCE_SERVER_ROOT=https://server
TEST_CONTAINER=/alice/

2. 运行Docker镜像：

shell
mkdir -p reports/ess
docker run -i --rm \
  -v "$(pwd)"/reports/ess:/reports \
  --env-file=ess.env \
  solidproject/conformance-test-harness \
  --output=/reports \
  --target=https://github.com/solid-contrib/conformance-test-harness/ess

使用提供的脚本

从https://github.com/solid-contrib/specification-tests/blob/main/run.sh%E4%B8%8B%E8%BD%BD%60run.sh%60%E8%84%9A%E6%9C%AC%EF%BC%8C%E5%88%9B%E5%BB%BA%60server.env%60%E6%96%87%E4%BB%B6%E5%90%8E%E6%89%A7%E8%A1%8C%EF%BC%9A

shell
# 运行内置测试
./run.sh server

# 运行本地测试
./run.sh -d . server

# 使用本地CTH构建
./run.sh -l server

测试报告

日志输出

包含测试结果摘要，示例：

json
{
  "resultDate": "2021-06-17T11:12:31.000Z",
  "elapsedTime": 7552.0,
  "mustFeatures": {"passed": 0, "failed": 0},
  "mustScenarios": {"passed": 0, "failed": 0},
  "features": {
    "MUST": {"passed": 0, "failed": 0},
    "MUSTNOT": {"passed": 0, "failed": 0},
    "SHOULD": {"passed": 0, "failed": 0},
    "SHOULDNOT": {"passed": 0, "failed": 0},
    "MAY": {"passed": 0, "failed": 0}
  },
  "scenarios": {
    "MUST": {"passed": 0, "failed": 0, "cantTell": 0, "untested": 0, "inapplicable": 0},
    "MUSTNOT": {"passed": 0, "failed": 0, "cantTell": 0, "untested": 0, "inapplicable": 0},
    "SHOULD": {"passed": 0, "failed": 0, "cantTell": 0, "untested": 0, "inapplicable": 0},
    "SHOULDNOT": {"passed": 0, "failed": 0, "cantTell": 0, "untested": 0, "inapplicable": 0},
    "MAY": {"passed": 0, "failed": 0, "cantTell": 0, "untested": 0, "inapplicable": 0}
  },
  "totalTime": 7552.0
}

输出报告文件

报告包含规范测试摘要、测试用例结果、详细日志和结果统计，可用于评估服务器对Solid规范的符合程度。