README.en.md · OpenCloudOS/os_smoke

# OS Smoke

#### Description

OS Smoke is a lightweight, automated OS smoke testing tool. It is designed to perform a quick "health check" immediately after an OS image is built, verifying that critical components such as the kernel, base system, drivers, applications, and development tools are functioning properly.

#### Software Architecture

```
os_smoke/
├── control                        # Test suite configuration (name, deps, build commands)
├── pre_init.sh                    # Pre-hooks (called before compile/test)
├── post_uninit.sh                 # Post-hooks (called after compile/test)
├── baseline/                      # Test case baseline definitions
│   ├── cases                      # Full test case list
│   ├── cases_kernel               # Kernel test cases
│   ├── cases_baseos               # Base OS test cases
│   ├── cases_app                  # Application test cases
│   ├── cases_develop              # Development tool test cases
│   └── cases_driver               # Driver test cases
├── tools/                         # Core test framework
│   ├── tos_test.sh                # Test execution engine (main dispatcher)
│   ├── case_lib.sh                # Shell test framework library
│   ├── case_lib.py                # Python test framework library
│   └── case_lib.c                 # C test framework library
└── os_smoke_src/                  # Test suite source code
    ├── Makefile                   # Top-level build file
    ├── lib/
    │   └── common_libs.sh         # Common library functions (package management, etc.)
    └── testcases/                 # Test case directories
        ├── kernel/                # Kernel cases
        ├── baseos/                # Base OS cases
        ├── app/                   # Application cases
        ├── develop/               # Development tool cases
        └── driver/                # Driver cases
```

The project provides unified test framework libraries in C, Python, and Shell (`tools/case_lib.*`), supporting consistent result reporting (`TPASS/TFAIL/TCONF/TWARN/TINFO`), safe file operations, and virtual machine detection.

#### System Requirements

- Minimum: 4 CPU cores / 8 GB RAM / 20 GB Disk
- Operating System: Linux

#### Installation

1. Clone the repository to the target test machine:
   ```bash
   git clone <repository-url>
   cd os_smoke
   ```

2. Install test suite dependencies:
   ```bash
   ./tools/tos_test.sh pkg
   ```

3. Compile and install the test suite:
   ```bash
   ./tools/tos_test.sh compile
   ```

#### Instructions

1. Run the full smoke test:
   ```bash
   ./tools/tos_test.sh test
   ```

2. Run tests by category (supports kernel, baseos, app, develop, driver):
   ```bash
   ./tools/tos_test.sh test kernel
   ```

3. Run a single test case:
   ```bash
   ./tools/tos_test.sh case <case_name>
   ```

4. Clean build artifacts:
   ```bash
   ./tools/tos_test.sh clean
   ```

#### Result Query and Log Analysis

After testing, all logs and result files are stored in `/data/log/os_suites/os_smoke/`:

| File | Description |
|---|---|
| `os_smoke.result` | Summary result file, each line formatted as `PASS/FAIL: case_name time(seconds)` |
| `os_smoke.log` | Runtime log with detailed output from compilation and execution |
| `os_smoke.log.compile` | Compilation phase log (generated by `compile` command) |
| `<case_name>` | Individual log file for each test case |
| `<case_name>.dmesg` | Kernel dmesg snapshot, auto-saved when kernel anomalies are detected |

Query commands:

```bash
# View overall pass/fail summary
cat /data/log/os_suites/os_smoke/os_smoke.result

# Filter all failed cases
grep "^FAIL" /data/log/os_suites/os_smoke/os_smoke.result

# View detailed log of a specific failed case
cat /data/log/os_suites/os_smoke/<case_name>

# Check for kernel anomalies (dmesg snapshots)
ls /data/log/os_suites/os_smoke/*.dmesg 2>/dev/null

# Count pass/fail totals
echo "PASS: $(grep -c '^PASS' /data/log/os_suites/os_smoke/os_smoke.result)"
echo "FAIL: $(grep -c '^FAIL' /data/log/os_suites/os_smoke/os_smoke.result)"
```

When running tests by category, the result file is named `os_smoke_<category>.result` (e.g., `os_smoke_kernel.result`).

#### Adding Test Cases

1. Create a case directory and script under `os_smoke_src/testcases/<category>/`
2. In the test script, source the framework library and use the API to report results:
   ```bash
   source case_lib.sh

# Report test passed
   tst_res $TPASS "Feature X verified successfully"

# Report test failed
   tst_res $TFAIL "Feature X returned unexpected value"

# Skip test (environment not met, etc.)
   tst_res $TCONF "Missing dependency, skipping test"

# Report warning (non-fatal)
   tst_res $TWARN "Performance below expected threshold"

# Output informational message (does not affect result)
   tst_res $TINFO "Current kernel version: $(uname -r)"

# Fatal error, abort test case immediately
   tst_brk $TFAIL "Failed to create test directory"
   tst_brk $TCONF "Unsupported architecture, skipping"

# Safe command execution (auto-aborts on failure)
   SAFE_CMD "Create temp directory" mkdir -p /tmp/test_dir
   ```
3. Register the case in `baseline/cases` and the corresponding category file, using the format:
   ```
   case_name; cd os_smoke/testcases/category/subdir; ./case_script.sh
   ```

#### Other

##### 1. Environment Cleanup

Clean log files:
```bash
# Backup old logs (recommended)
timestamp=$(date +%Y%m%d_%H%M%S)
mv /data/log/os_suites/os_smoke /data/log/os_suites/os_smoke.bak_${timestamp}

# Or delete old logs directly
rm -rf /data/log/os_suites/os_smoke/*
```

##### 2. Custom Configuration

Modify timeout:
```bash
# Edit the control file
vim control

# Add or modify timeout configuration
CONTROL_CASE_TIMEOUT=3600  # Set to 1 hour
```

Add custom dependency packages:
```bash
# Edit the control file
vim control

# Modify dependency package list (note: only common packages are configured here)
CONTROL_PRE_PKG='gcc automake expect kernel-devel your_package'
```

##### 3. Disk Device Configuration

Configure real disk devices (optional):
```bash
# Edit the control file
vim control

# Add disk device configuration (if the system has spare disks)
CONTROL_CASE_DISK_DEVICE="/dev/sdb"

# Multiple disk devices
CONTROL_CASE_DISK_DEVICE="/dev/sdb /dev/sdc"
```

**Note**: If this is not configured, disk-related tests will automatically use loopback devices for simulation.

#### Contribution

1. Fork the repository
2. Create a Feat\_xxx branch
3. Commit your code
4. Create a Pull Request

OpenCloudOS/os_smoke

简介

发行版

贡献者

语言

近期动态

OpenCloudOS/os_smoke .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

语言

近期动态

搜索帮助

OpenCloudOS/os_smoke