From c4b522ff09e80356c3a522788c5fc83ec81607c5 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Fri, 3 Jan 2025 14:15:29 +0800 Subject: [PATCH 01/56] update README structure for support linux/win/mac platforms by charles --- README.md | 337 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 198 insertions(+), 139 deletions(-) diff --git a/README.md b/README.md index e4814cee67..dfd1be23c7 100644 --- a/README.md +++ b/README.md @@ -26,24 +26,51 @@ English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine # Table of Contents -1. [What is TDengine?](#1-what-is-tdengine) -2. [Documentation](#2-documentation) -3. [Building](#3-building) - 1. [Install build tools](#31-install-build-tools) - 1. [Get the source codes](#32-get-the-source-codes) - 1. [Special Note](#33-special-note) - 1. [Build TDengine](#34-build-tdengine) -4. [Installing](#4-installing) - 1. [On Linux platform](#41-on-linux-platform) - 1. [On Windows platform](#42-on-windows-platform) - 1. [On macOS platform](#43-on-macos-platform) - 1. [Quick Run](#44-quick-run) -5. [Try TDengine](#5-try-tdengine) -6. [Developing with TDengine](#6-developing-with-tdengine) -7. [Contribute to TDengine](#7-contribute-to-tdengine) -8. [Join the TDengine Community](#8-join-the-tdengine-community) +- [Table of Contents](#table-of-contents) +- [1. Introduction](#1-introduction) +- [2. Documentation](#2-documentation) +- [3. Prerequisites](#3-prerequisites) + - [3.1 Install dependencies tools](#31-install-dependencies-tools) + - [3.1.1 Linux platform](#311-linux-platform) + - [Install the required package for linux](#install-the-required-package-for-linux) + - [Install Go for linux](#install-go-for-linux) + - [Install node for linux](#install-node-for-linux) + - [Install Python-connector for linux](#install-python-connector-for-linux) + - [3.1.2 Windows platform](#312-windows-platform) + - [Install the required package for windows](#install-the-required-package-for-windows) + - [3.1.3 MacOS platform](#313-macos-platform) + - [Install the required package for macOS](#install-the-required-package-for-macos) + - [3.2 Get the source codes](#32-get-the-source-codes) + - [3.3 Special Note](#33-special-note) +- [4. Building](#4-building) + - [4.1 Linux platform building](#41-linux-platform-building) + - [4.2 Windows platform building](#42-windows-platform-building) + - [4.3 MacOS platform building](#43-macos-platform-building) +- [5. Packaging](#5-packaging) + - [5.1 Linux platform packaging](#51-linux-platform-packaging) + - [5.2 Windows platform packaging](#52-windows-platform-packaging) + - [5.3 MacOS platform packaging](#53-macos-platform-packaging) +- [6. Installation](#6-installation) + - [6.1 Linux platform installation](#61-linux-platform-installation) + - [6.2 Windows platform installation](#62-windows-platform-installation) + - [6.3 MacOS platform installation](#63-macos-platform-installation) +- [7. Running](#7-running) + - [7.1 Linux platform](#71-linux-platform) + - [7.2 Windows platform](#72-windows-platform) + - [7.3 MacOS platform](#73-macos-platform) +- [8. Testing](#8-testing) + - [8.1 Linux platform testing](#81-linux-platform-testing) + - [8.2 Windows platform testing](#82-windows-platform-testing) + - [8.3 MacOS platform testing](#83-macos-platform-testing) +- [9. Releasing](#9-releasing) + - [9.1 Linux platform releasing](#91-linux-platform-releasing) + - [9.2 Windows platform realeasing](#92-windows-platform-realeasing) + - [9.3 MacOS platform releasing](#93-macos-platform-releasing) +- [10. CI/CD](#10-cicd) +- [11. Coverage](#11-coverage) +- [12. Contributing](#12-contributing) -# 1. What is TDengine？ +# 1. Introduction TDengine is an open source, high-performance, cloud native [time-series database](https://tdengine.com/tsdb/) optimized for Internet of Things (IoT), Connected Cars, and Industrial IoT. It enables efficient, real-time data ingestion, processing, and monitoring of TB and even PB scale data per day, generated by billions of sensors and data collectors. TDengine differentiates itself from other time-series databases with the following advantages: @@ -65,109 +92,127 @@ For a full list of TDengine competitive advantages, please [check here](https:// For user manual, system design and architecture, please refer to [TDengine Documentation](https://docs.tdengine.com) ([TDengine 文档](https://docs.taosdata.com)) -# 3. Building +# 3. Prerequisites -At the moment, TDengine server supports running on Linux/Windows/macOS systems. Any application can also choose the RESTful interface provided by taosAdapter to connect the taosd service . TDengine supports X64/ARM64 CPU, and it will support MIPS64, Alpha64, ARM32, RISC-V and other CPU architectures in the future. Right now we don't support build with cross-compiling environment. +List the software and tools required to work on the project. -You can choose to install through source code, [container](https://docs.tdengine.com/get-started/docker/), [installation package](https://docs.tdengine.com/get-started/package/) or [Kubernetes](https://docs.tdengine.com/deployment/k8s/). This quick guide only applies to installing from source. +- go 1.20+ (for taosadapter) +- node 16.20.2 (for taos-explorer) +- python 3.10.12+ (for test) -TDengine provide a few useful tools such as taosBenchmark (was named taosdemo) and taosdump. They were part of TDengine. By default, TDengine compiling does not include taosTools. You can use `cmake .. -DBUILD_TOOLS=true` to make them be compiled with TDengine. +Step-by-step instructions to set up the prerequisites software. -To build TDengine, use [CMake](https://cmake.org/) 3.13.0 or higher versions in the project directory. +## 3.1 Install dependencies tools -## 3.1 Install build tools +### 3.1.1 Linux platform -### Ubuntu 18.04 and above or Debian +#### Install the required package for linux ```bash -sudo apt-get install -y gcc cmake build-essential git libssl-dev libgflags2.2 libgflags-dev +apt-get install -y llvm gcc make cmake libssl-dev pkg-config perl g++ lzma curl locales psmisc sudo tree libgeos-dev libgflags2.2 libgflags-dev libgoogle-glog-dev libjansson-dev libsnappy-dev liblzma-dev libz-dev zlib1g build-essential valgrind rsync vim libjemalloc-dev openssh-server screen sshpass net-tools dirmngr gnupg apt-transport-https ca-certificates software-properties-common r-base iputils-ping ``` -#### Install build dependencies for taosTools +#### Install Go for linux -To build the [taosTools](https://github.com/taosdata/taos-tools) on Ubuntu/Debian, the following packages need to be installed. +Update the installation package to version 1.23.3. ```bash -sudo apt install build-essential libjansson-dev libsnappy-dev liblzma-dev libz-dev zlib1g pkg-config +cd /usr/local/ +wget https://golang.google.cn/dl/go1.23.3.linux-amd64.tar.gz +rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.3.linux-amd64.tar.gz ``` -### CentOS 7.9 +Set up environment variables, first add the following content to the end of the `~/.bashrc` file. ```bash -sudo yum install epel-release -sudo yum update -sudo yum install -y gcc gcc-c++ make cmake3 gflags git openssl-devel -sudo ln -sf /usr/bin/cmake3 /usr/bin/cmake +export GO_HOME=/usr/local/go +export PATH=$GO_HOME/bin:$PATH +export CGO_ENABLED=1 ``` -### CentOS 8/Fedora/Rocky Linux +Then make the environment variables take effect. ```bash -sudo dnf install -y gcc gcc-c++ make cmake epel-release gflags git openssl-devel +source ~/.bashrc ``` -#### Install build dependencies for taosTools on CentOS +Configure proxy to accelerate the download of Go dependencies. -#### CentOS 7.9 - -``` -sudo yum install -y zlib-devel zlib-static xz-devel snappy-devel jansson jansson-devel pkgconfig libatomic libatomic-static libstdc++-static openssl-devel +```bash +go env -w GOPROXY=https://goproxy.cn,direct +go env -w GO111MODULE=on ``` -#### CentOS 8/Fedora/Rocky Linux +Check if the environment variables have taken effect and if the version is the installed version. -``` -sudo yum install -y epel-release -sudo yum install -y dnf-plugins-core -sudo yum config-manager --set-enabled powertools -sudo yum install -y zlib-devel zlib-static xz-devel snappy-devel jansson jansson-devel pkgconfig libatomic libatomic-static libstdc++-static openssl-devel +```bash +go env +go version ``` -Note: Since snappy lacks pkg-config support (refer to [link](https://github.com/google/snappy/pull/86)), it leads a cmake prompt libsnappy not found. But snappy still works well. +#### Install node for linux -If the PowerTools installation fails, you can try to use: +Recommend install node using nvm. -``` -sudo yum config-manager --set-enabled powertools +```bash +curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash ``` -#### For CentOS + devtoolset +Set up environment variables, add the following content to the end of the `~/.bashrc` file. -Besides above dependencies, please run following commands: - -``` -sudo yum install centos-release-scl -sudo yum install devtoolset-9 devtoolset-9-libatomic-devel -scl enable devtoolset-9 -- bash +```bash +export NVM_DIR="$HOME/.nvm" +[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" ``` -### macOS +Then make the environment variables take effect. + +```bash +source ~/.bashrc +``` + +Finally, Install node and yarn. + +```bash +nvm install 16.20.2 +npm config set registry=https://registry.npmmirror.com +npm install -g yarn +``` + +#### Install Python-connector for linux + +Install Python3. + +```bash +apt install python3 +apt install python3-pip +``` + +Install the dependent Python components. + +```bash +pip3 install pandas psutil fabric2 requests faker simplejson toml pexpect tzlocal distro decorator loguru hyperloglog +``` + +Install the Python connector for TDengine. + +```bash +pip3 install taospy taos-ws-py +``` + +### 3.1.2 Windows platform + +#### Install the required package for windows + + +### 3.1.3 MacOS platform + +#### Install the required package for macOS ``` brew install argp-standalone gflags pkgconfig ``` -### Setup golang environment - -TDengine includes a few components like taosAdapter developed by Go language. Please refer to golang.org official documentation for golang environment setup. - -Please use version 1.20+. For the user in China, we recommend using a proxy to accelerate package downloading. - -``` -go env -w GO111MODULE=on -go env -w GOPROXY=https://goproxy.cn,direct -``` - -The default will not build taosAdapter, but you can use the following command to build taosAdapter as the service for RESTful interface. - -``` -cmake .. -DBUILD_HTTP=false -``` - -### Setup rust environment - -TDengine includes a few components developed by Rust language. Please refer to rust-lang.org official documentation for rust environment setup. - ## 3.2 Get the source codes First of all, you may clone the source codes from github: @@ -188,9 +233,17 @@ You can modify the file ~/.gitconfig to use ssh protocol instead of https for be [JDBC Connector](https://github.com/taosdata/taos-connector-jdbc)， [Go Connector](https://github.com/taosdata/driver-go)，[Python Connector](https://github.com/taosdata/taos-connector-python)，[Node.js Connector](https://github.com/taosdata/taos-connector-node)，[C# Connector](https://github.com/taosdata/taos-connector-dotnet) ，[Rust Connector](https://github.com/taosdata/taos-connector-rust) and [Grafana plugin](https://github.com/taosdata/grafanaplugin) has been moved to standalone repository. -## 3.4 Build TDengine +# 4. Building -### On Linux platform +At the moment, TDengine server supports running on Linux/Windows/MacOS systems. Any application can also choose the RESTful interface provided by taosAdapter to connect the taosd service. TDengine supports X64/ARM64 CPU, and it will support MIPS64, Alpha64, ARM32, RISC-V and other CPU architectures in the future. Right now we don't support build with cross-compiling environment. + +You can choose to install through source code, [container](https://docs.tdengine.com/get-started/docker/), [installation package](https://docs.tdengine.com/get-started/package/) or [Kubernetes](https://docs.tdengine.com/deployment/k8s/). This quick guide only applies to installing from source. + +TDengine provide a few useful tools such as taosBenchmark (was named taosdemo) and taosdump. They were part of TDengine. By default, TDengine compiling does not include taosTools. You can use `cmake .. -DBUILD_TOOLS=true` to make them be compiled with TDengine. + +To build TDengine, use [CMake](https://cmake.org/) 3.13.0 or higher versions in the project directory. + +## 4.1 Linux platform building You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below: @@ -223,7 +276,7 @@ aarch64: cmake .. -DCPUTYPE=aarch64 && cmake --build . ``` -### On Windows platform +## 4.2 Windows platform building If you use the Visual Studio 2013, please open a command window by executing "cmd.exe". Please specify "amd64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. @@ -255,7 +308,7 @@ cmake .. -G "NMake Makefiles" nmake ``` -### On macOS platform +## 4.3 MacOS platform building Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur. @@ -264,9 +317,17 @@ mkdir debug && cd debug cmake .. && cmake --build . ``` -# 4. Installing +# 5. Packaging -## 4.1 On Linux platform +## 5.1 Linux platform packaging + +## 5.2 Windows platform packaging + +## 5.3 MacOS platform packaging + +# 6. Installation + +## 6.1 Linux platform installation After building successfully, TDengine can be installed by @@ -278,21 +339,7 @@ Users can find more information about directories installed on the system in the Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/package/) for it. -To start the service after installation, in a terminal, use: - -```bash -sudo systemctl start taosd -``` - -Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: - -```bash -taos -``` - -If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. - -## 4.2 On Windows platform +## 6.2 Windows platform installation After building successfully, TDengine can be installed by: @@ -300,7 +347,7 @@ After building successfully, TDengine can be installed by: nmake install ``` -## 4.3 On macOS platform +## 6.3 MacOS platform installation After building successfully, TDengine can be installed by: @@ -326,7 +373,23 @@ taos If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. -## 4.4 Quick Run +# 7. Running + +## 7.1 Linux platform + +To start the service after installation, in a terminal, use: + +```bash +sudo systemctl start taosd +``` + +Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: + +```bash +taos +``` + +If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. If you don't want to run TDengine as a service, you can run it in current shell. For example, to quickly start a TDengine server after building, run the command below in terminal: (We take Linux as an example, command on Windows will be `taosd.exe`) @@ -342,48 +405,44 @@ In another terminal, use the TDengine CLI to connect the server: option "-c test/cfg" specifies the system configuration file directory. -# 5. Try TDengine +## 7.2 Windows platform -It is easy to run SQL commands from TDengine CLI which is the same as other SQL databases. +## 7.3 MacOS platform -```sql -CREATE DATABASE demo; -USE demo; -CREATE TABLE t (ts TIMESTAMP, speed INT); -INSERT INTO t VALUES('2019-07-15 00:00:00', 10); -INSERT INTO t VALUES('2019-07-15 01:00:00', 20); -SELECT * FROM t; - ts | speed | -=================================== - 19-07-15 00:00:00.000| 10| - 19-07-15 01:00:00.000| 20| -Query OK, 2 row(s) in set (0.001700s) +# 8. Testing + +## 8.1 Linux platform testing + +## 8.2 Windows platform testing + +## 8.3 MacOS platform testing + +# 9. Releasing + +## 9.1 Linux platform releasing + +## 9.2 Windows platform realeasing + +## 9.3 MacOS platform releasing + +# 10. CI/CD +We use jenkins for CI/CD workflow configuration. See http://ci.bl.taosdata.com:8080/job/NewTest/view/change-requests/ +We can also run ci script locally. + +```bash +cd /root/TDengine/tests +./run_all_ci_cases.sh ``` -# 6. Developing with TDengine +# 11. Coverage +We can see coverage result in https://coveralls.io/github/taosdata/TDengine +We can also run coverage script locally. -## Official Connectors +```bash +cd /root/TDengine/tests +./run_local_coverage.sh +``` -TDengine provides abundant developing tools for users to develop on TDengine. Follow the links below to find your desired connectors and relevant documentation. - -- [Java](https://docs.tdengine.com/reference/connectors/java/) -- [C/C++](https://docs.tdengine.com/reference/connectors/cpp/) -- [Python](https://docs.tdengine.com/reference/connectors/python/) -- [Go](https://docs.tdengine.com/reference/connectors/go/) -- [Node.js](https://docs.tdengine.com/reference/connectors/node/) -- [Rust](https://docs.tdengine.com/reference/connectors/rust/) -- [C#](https://docs.tdengine.com/reference/connectors/csharp/) -- [RESTful API](https://docs.tdengine.com/reference/connectors/rest-api/) - -# 7. Contribute to TDengine +# 12. Contributing Please follow the [contribution guidelines](CONTRIBUTING.md) to contribute to the project. - -# 8. Join the TDengine Community - -For more information about TDengine, you can follow us on social media and join our Discord server: - -- [Discord](https://discord.com/invite/VZdSuUg4pS) -- [Twitter](https://twitter.com/TDengineDB) -- [LinkedIn](https://www.linkedin.com/company/tdengine/) -- [YouTube](https://www.youtube.com/@tdengine) From 5822d7a6b0ce27b662deb4b8e7740753adba847e Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Mon, 6 Jan 2025 17:53:28 +0800 Subject: [PATCH 02/56] doc:add test cases --- README.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 61 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index dfd1be23c7..363194f202 100644 --- a/README.md +++ b/README.md @@ -413,6 +413,64 @@ option "-c test/cfg" specifies the system configuration file directory. ## 8.1 Linux platform testing +### 8.1.1 Run the TSIM test script +Run the TSIM test script to simulate TDengine. +```bash +cd /root/TDengine/tests/script +./test.sh -f tsim/db/basic1.sim +``` + +### 8.1.2 Run the Python test script +Run the Python test script to simulate TDengine. +```bash +cd /root/TDengine/tests/system-test +python3 ./test.py -f 2-query/floor.py +``` + +### 8.1.3 Run unittest +Run the unit test script to simulate TDengine. +```bash +cd /root/TDengine/tests/unit-test/ +bash test.sh +``` + +### 8.1.4 Smoke Testing +Run the smoke test script to simulate TDengine. +```bash +cd /root/TDengine/packaging/smokeTest +./test_smoking_selfhost.sh +``` + +### 8.1.5 TSBS Test --replace +Run the TSBS test script to simulate TDengine. +1. Clone the code +```bash +cd /root && git clone https://github.com/taosdata/tsbs.git && cd tsbs/scripts/tsdbComp +``` +2. Modify IP and host of client and server in `test.ini` +```ini +clientIP="192.168.0.203" # client ip +clientHost="trd03" # client hostname +serverIP="192.168.0.204" # server ip +serverHost="trd04" # server hostname +``` +3. Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: +```ini +serverPass="taosdata123" # server root password +``` +4. Run the following command to start the test: + ```bash +nohup bash tsdbComparison.sh > test.log & +``` +5. When the test is done, the result can be found in `/data2/` directory, which can also be configured in `test.ini`. + +### 8.1.6 Crash_gen Test +Run the crash_gen script to simulate TDengine. +```bash +cd /root/TDengine/tests/pytest/ && ./crash_gen.sh +``` + + ## 8.2 Windows platform testing ## 8.3 MacOS platform testing @@ -425,16 +483,16 @@ option "-c test/cfg" specifies the system configuration file directory. ## 9.3 MacOS platform releasing -# 10. CI/CD +# 10. CI/CD We use jenkins for CI/CD workflow configuration. See http://ci.bl.taosdata.com:8080/job/NewTest/view/change-requests/ We can also run ci script locally. ```bash cd /root/TDengine/tests -./run_all_ci_cases.sh +./run_all_ci_cases.sh -b main ``` -# 11. Coverage +# 11. Coverage --replace We can see coverage result in https://coveralls.io/github/taosdata/TDengine We can also run coverage script locally. From 1e2e526f960ec13103e0909ce72a27f8bcd697e6 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Tue, 7 Jan 2025 14:56:40 +0800 Subject: [PATCH 03/56] update structure of readme to remove the second layer title by charles --- README.md | 188 ++++++++++++++++++++++++++---------------------------- 1 file changed, 89 insertions(+), 99 deletions(-) diff --git a/README.md b/README.md index 363194f202..62c3d6c5c9 100644 --- a/README.md +++ b/README.md @@ -31,43 +31,22 @@ English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine - [2. Documentation](#2-documentation) - [3. Prerequisites](#3-prerequisites) - [3.1 Install dependencies tools](#31-install-dependencies-tools) - - [3.1.1 Linux platform](#311-linux-platform) - - [Install the required package for linux](#install-the-required-package-for-linux) - - [Install Go for linux](#install-go-for-linux) - - [Install node for linux](#install-node-for-linux) - - [Install Python-connector for linux](#install-python-connector-for-linux) - - [3.1.2 Windows platform](#312-windows-platform) - - [Install the required package for windows](#install-the-required-package-for-windows) - - [3.1.3 MacOS platform](#313-macos-platform) - - [Install the required package for macOS](#install-the-required-package-for-macos) - [3.2 Get the source codes](#32-get-the-source-codes) - [3.3 Special Note](#33-special-note) - [4. Building](#4-building) - - [4.1 Linux platform building](#41-linux-platform-building) - - [4.2 Windows platform building](#42-windows-platform-building) - - [4.3 MacOS platform building](#43-macos-platform-building) - [5. Packaging](#5-packaging) - - [5.1 Linux platform packaging](#51-linux-platform-packaging) - - [5.2 Windows platform packaging](#52-windows-platform-packaging) - - [5.3 MacOS platform packaging](#53-macos-platform-packaging) - [6. Installation](#6-installation) - - [6.1 Linux platform installation](#61-linux-platform-installation) - - [6.2 Windows platform installation](#62-windows-platform-installation) - - [6.3 MacOS platform installation](#63-macos-platform-installation) - [7. Running](#7-running) - - [7.1 Linux platform](#71-linux-platform) - - [7.2 Windows platform](#72-windows-platform) - - [7.3 MacOS platform](#73-macos-platform) - [8. Testing](#8-testing) - - [8.1 Linux platform testing](#81-linux-platform-testing) - - [8.2 Windows platform testing](#82-windows-platform-testing) - - [8.3 MacOS platform testing](#83-macos-platform-testing) + - [8.1 Run the TSIM test script](#81-run-the-tsim-test-script) + - [8.2 Run the Python test script](#82-run-the-python-test-script) + - [8.3 Run unittest](#83-run-unittest) + - [8.4 Smoke Testing](#84-smoke-testing) + - [8.5 TSBS Test --replace](#85-tsbs-test---replace) + - [8.6 Crash\_gen Test](#86-crash_gen-test) - [9. Releasing](#9-releasing) - - [9.1 Linux platform releasing](#91-linux-platform-releasing) - - [9.2 Windows platform realeasing](#92-windows-platform-realeasing) - - [9.3 MacOS platform releasing](#93-macos-platform-releasing) - [10. CI/CD](#10-cicd) -- [11. Coverage](#11-coverage) +- [11. Coverage --replace](#11-coverage---replace) - [12. Contributing](#12-contributing) # 1. Introduction @@ -104,15 +83,13 @@ Step-by-step instructions to set up the prerequisites software. ## 3.1 Install dependencies tools -### 3.1.1 Linux platform - -#### Install the required package for linux +Install the required package for linux ```bash apt-get install -y llvm gcc make cmake libssl-dev pkg-config perl g++ lzma curl locales psmisc sudo tree libgeos-dev libgflags2.2 libgflags-dev libgoogle-glog-dev libjansson-dev libsnappy-dev liblzma-dev libz-dev zlib1g build-essential valgrind rsync vim libjemalloc-dev openssh-server screen sshpass net-tools dirmngr gnupg apt-transport-https ca-certificates software-properties-common r-base iputils-ping ``` -#### Install Go for linux +Install Go for linux Update the installation package to version 1.23.3. @@ -150,7 +127,7 @@ go env go version ``` -#### Install node for linux +Install node for linux Recommend install node using nvm. @@ -179,7 +156,7 @@ npm config set registry=https://registry.npmmirror.com npm install -g yarn ``` -#### Install Python-connector for linux +Install Python-connector for linux Install Python3. @@ -200,14 +177,11 @@ Install the Python connector for TDengine. pip3 install taospy taos-ws-py ``` -### 3.1.2 Windows platform +Install the required package for windows -#### Install the required package for windows +to be updated... - -### 3.1.3 MacOS platform - -#### Install the required package for macOS +Install the required package for macOS ``` brew install argp-standalone gflags pkgconfig @@ -243,7 +217,7 @@ TDengine provide a few useful tools such as taosBenchmark (was named taosdemo) a To build TDengine, use [CMake](https://cmake.org/) 3.13.0 or higher versions in the project directory. -## 4.1 Linux platform building +Linux platform building You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below: @@ -276,7 +250,7 @@ aarch64: cmake .. -DCPUTYPE=aarch64 && cmake --build . ``` -## 4.2 Windows platform building +4.2 Windows platform building If you use the Visual Studio 2013, please open a command window by executing "cmd.exe". Please specify "amd64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. @@ -308,7 +282,7 @@ cmake .. -G "NMake Makefiles" nmake ``` -## 4.3 MacOS platform building +MacOS platform building Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur. @@ -319,15 +293,21 @@ cmake .. && cmake --build . # 5. Packaging -## 5.1 Linux platform packaging +Linux platform packaging -## 5.2 Windows platform packaging +to be updated... -## 5.3 MacOS platform packaging +Windows platform packaging + +to be updated... + +MacOS platform packaging + +to be updated... # 6. Installation -## 6.1 Linux platform installation +Linux platform installation After building successfully, TDengine can be installed by @@ -337,9 +317,9 @@ sudo make install Users can find more information about directories installed on the system in the [directory and files](https://docs.tdengine.com/reference/directory/) section. -Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/package/) for it. +Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/deploy-from-package/) for it. -## 6.2 Windows platform installation +Windows platform installation After building successfully, TDengine can be installed by: @@ -347,7 +327,7 @@ After building successfully, TDengine can be installed by: nmake install ``` -## 6.3 MacOS platform installation +MacOS platform installation After building successfully, TDengine can be installed by: @@ -355,29 +335,9 @@ After building successfully, TDengine can be installed by: sudo make install ``` -Users can find more information about directories installed on the system in the [directory and files](https://docs.tdengine.com/reference/directory/) section. - -Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/package/) for it. - -To start the service after installation, double-click the /applications/TDengine to start the program, or in a terminal, use: - -```bash -sudo launchctl start com.tdengine.taosd -``` - -Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: - -```bash -taos -``` - -If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. - # 7. Running -## 7.1 Linux platform - -To start the service after installation, in a terminal, use: +To start the service after installation on linux, in a terminal, use: ```bash sudo systemctl start taosd @@ -405,87 +365,117 @@ In another terminal, use the TDengine CLI to connect the server: option "-c test/cfg" specifies the system configuration file directory. -## 7.2 Windows platform +To start the service after installation on windows, in a terminal, use: -## 7.3 MacOS platform +```bash +to be updated +``` +Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: + +```bash +to be updated +``` + +To start the service after installation on macOS, double-click the /applications/TDengine to start the program, or in a terminal, use: + +```bash +sudo launchctl start com.tdengine.taosd +``` + +Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: + +```bash +taos +``` + +If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. # 8. Testing -## 8.1 Linux platform testing +## 8.1 Run the TSIM test script + +TSIM test framework is developed by c++ in the start-up period of TDengine， the test scripts are basic cases, you can run +the script with below command: -### 8.1.1 Run the TSIM test script -Run the TSIM test script to simulate TDengine. ```bash cd /root/TDengine/tests/script ./test.sh -f tsim/db/basic1.sim ``` -### 8.1.2 Run the Python test script -Run the Python test script to simulate TDengine. +## 8.2 Run the Python test script +Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only +work for TDengine enterprise version, you can run the script with below command: + ```bash cd /root/TDengine/tests/system-test python3 ./test.py -f 2-query/floor.py ``` -### 8.1.3 Run unittest -Run the unit test script to simulate TDengine. +## 8.3 Run unittest +Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run +the script with below command: + ```bash cd /root/TDengine/tests/unit-test/ bash test.sh ``` -### 8.1.4 Smoke Testing -Run the smoke test script to simulate TDengine. +## 8.4 Smoke Testing +Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine, you can run the +script with below command: + ```bash cd /root/TDengine/packaging/smokeTest ./test_smoking_selfhost.sh ``` -### 8.1.5 TSBS Test --replace -Run the TSBS test script to simulate TDengine. +## 8.5 TSBS Test --replace +The Time Series Benchmark Suite(TSBS) test script provides a standardized approach to evaluate the performance of various +time series databases, you can run the script with below command: + 1. Clone the code ```bash cd /root && git clone https://github.com/taosdata/tsbs.git && cd tsbs/scripts/tsdbComp ``` -2. Modify IP and host of client and server in `test.ini` +1. Modify IP and host of client and server in `test.ini` ```ini clientIP="192.168.0.203" # client ip clientHost="trd03" # client hostname serverIP="192.168.0.204" # server ip serverHost="trd04" # server hostname ``` -3. Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: +1. Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: ```ini serverPass="taosdata123" # server root password ``` -4. Run the following command to start the test: +1. Run the following command to start the test: ```bash nohup bash tsdbComparison.sh > test.log & ``` -5. When the test is done, the result can be found in `/data2/` directory, which can also be configured in `test.ini`. +1. When the test is done, the result can be found in `/data2/` directory, which can also be configured in `test.ini`. + +## 8.6 Crash_gen Test +Crash_gen is a chaotic testing tool developed by TDengine, it can evaluate the resilience of TDengine through simulating +normal operation、intentional fault injection and their combination, you can run the script with below command: -### 8.1.6 Crash_gen Test -Run the crash_gen script to simulate TDengine. ```bash cd /root/TDengine/tests/pytest/ && ./crash_gen.sh ``` +Windows platform testing -## 8.2 Windows platform testing +to be updated... -## 8.3 MacOS platform testing +MacOS platform testing + +to be updated... # 9. Releasing -## 9.1 Linux platform releasing - -## 9.2 Windows platform realeasing - -## 9.3 MacOS platform releasing +You can access the [Release](https://github.com/taosdata/TDengine/releases) for TDengine release version list. # 10. CI/CD -We use jenkins for CI/CD workflow configuration. See http://ci.bl.taosdata.com:8080/job/NewTest/view/change-requests/ -We can also run ci script locally. +You can run ci script locally with below commands: ```bash cd /root/TDengine/tests From 16d15427120495d837e508adb18c10ebb60bf4b4 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Tue, 7 Jan 2025 16:44:39 +0800 Subject: [PATCH 04/56] udpate README to remove the second layer section for Building and Testing by charles --- README.md | 528 ++++++++++++++++++++++++++---------------------------- 1 file changed, 259 insertions(+), 269 deletions(-) diff --git a/README.md b/README.md index 62c3d6c5c9..d843f98ffa 100644 --- a/README.md +++ b/README.md @@ -30,20 +30,11 @@ English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine - [1. Introduction](#1-introduction) - [2. Documentation](#2-documentation) - [3. Prerequisites](#3-prerequisites) - - [3.1 Install dependencies tools](#31-install-dependencies-tools) - - [3.2 Get the source codes](#32-get-the-source-codes) - - [3.3 Special Note](#33-special-note) - [4. Building](#4-building) - [5. Packaging](#5-packaging) - [6. Installation](#6-installation) - [7. Running](#7-running) - [8. Testing](#8-testing) - - [8.1 Run the TSIM test script](#81-run-the-tsim-test-script) - - [8.2 Run the Python test script](#82-run-the-python-test-script) - - [8.3 Run unittest](#83-run-unittest) - - [8.4 Smoke Testing](#84-smoke-testing) - - [8.5 TSBS Test --replace](#85-tsbs-test---replace) - - [8.6 Crash\_gen Test](#86-crash_gen-test) - [9. Releasing](#9-releasing) - [10. CI/CD](#10-cicd) - [11. Coverage --replace](#11-coverage---replace) @@ -81,131 +72,130 @@ List the software and tools required to work on the project. Step-by-step instructions to set up the prerequisites software. -## 3.1 Install dependencies tools +- Install dependencies tools -Install the required package for linux + - The required package for linux -```bash -apt-get install -y llvm gcc make cmake libssl-dev pkg-config perl g++ lzma curl locales psmisc sudo tree libgeos-dev libgflags2.2 libgflags-dev libgoogle-glog-dev libjansson-dev libsnappy-dev liblzma-dev libz-dev zlib1g build-essential valgrind rsync vim libjemalloc-dev openssh-server screen sshpass net-tools dirmngr gnupg apt-transport-https ca-certificates software-properties-common r-base iputils-ping -``` + ```bash + apt-get install -y llvm gcc make cmake libssl-dev pkg-config perl g++ lzma curl locales psmisc sudo tree libgeos-dev libgflags2.2 libgflags-dev libgoogle-glog-dev libjansson-dev libsnappy-dev liblzma-dev libz-dev zlib1g build-essential valgrind rsync vim libjemalloc-dev openssh-server screen sshpass net-tools dirmngr gnupg apt-transport-https ca-certificates software-properties-common r-base iputils-ping + ``` -Install Go for linux + Install Go for linux -Update the installation package to version 1.23.3. + Update the installation package to version 1.23.3. -```bash -cd /usr/local/ -wget https://golang.google.cn/dl/go1.23.3.linux-amd64.tar.gz -rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.3.linux-amd64.tar.gz -``` + ```bash + cd /usr/local/ + wget https://golang.google.cn/dl/go1.23.3.linux-amd64.tar.gz + rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.3.linux-amd64.tar.gz + ``` -Set up environment variables, first add the following content to the end of the `~/.bashrc` file. + Set up environment variables, first add the following content to the end of the `~/.bashrc` file. -```bash -export GO_HOME=/usr/local/go -export PATH=$GO_HOME/bin:$PATH -export CGO_ENABLED=1 -``` + ```bash + export GO_HOME=/usr/local/go + export PATH=$GO_HOME/bin:$PATH + export CGO_ENABLED=1 + ``` -Then make the environment variables take effect. + Then make the environment variables take effect. -```bash -source ~/.bashrc -``` + ```bash + source ~/.bashrc + ``` -Configure proxy to accelerate the download of Go dependencies. + Configure proxy to accelerate the download of Go dependencies. -```bash -go env -w GOPROXY=https://goproxy.cn,direct -go env -w GO111MODULE=on -``` + ```bash + go env -w GOPROXY=https://goproxy.cn,direct + go env -w GO111MODULE=on + ``` -Check if the environment variables have taken effect and if the version is the installed version. + Check if the environment variables have taken effect and if the version is the installed version. -```bash -go env -go version -``` + ```bash + go env + go version + ``` -Install node for linux + Install node for linux -Recommend install node using nvm. + Recommend install node using nvm. -```bash -curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash -``` + ```bash + curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash + ``` -Set up environment variables, add the following content to the end of the `~/.bashrc` file. + Set up environment variables, add the following content to the end of the `~/.bashrc` file. -```bash -export NVM_DIR="$HOME/.nvm" -[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" -``` + ```bash + export NVM_DIR="$HOME/.nvm" + [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" + ``` -Then make the environment variables take effect. + Then make the environment variables take effect. -```bash -source ~/.bashrc -``` + ```bash + source ~/.bashrc + ``` -Finally, Install node and yarn. + Finally, Install node and yarn. -```bash -nvm install 16.20.2 -npm config set registry=https://registry.npmmirror.com -npm install -g yarn -``` + ```bash + nvm install 16.20.2 + npm config set registry=https://registry.npmmirror.com + npm install -g yarn + ``` -Install Python-connector for linux + Install Python-connector for linux -Install Python3. + Install Python3. -```bash -apt install python3 -apt install python3-pip -``` + ```bash + apt install python3 + apt install python3-pip + ``` -Install the dependent Python components. + Install the dependent Python components. -```bash -pip3 install pandas psutil fabric2 requests faker simplejson toml pexpect tzlocal distro decorator loguru hyperloglog -``` + ```bash + pip3 install pandas psutil fabric2 requests faker simplejson toml pexpect tzlocal distro decorator loguru hyperloglog + ``` -Install the Python connector for TDengine. + Install the Python connector for TDengine. -```bash -pip3 install taospy taos-ws-py -``` + ```bash + pip3 install taospy taos-ws-py + ``` -Install the required package for windows + - The required package for windows -to be updated... + to be updated... -Install the required package for macOS + - The required package for macOS -``` -brew install argp-standalone gflags pkgconfig -``` + ``` + brew install argp-standalone gflags pkgconfig + ``` -## 3.2 Get the source codes +- Get the source codes -First of all, you may clone the source codes from github: + First of all, you may clone the source codes from github: -```bash -git clone https://github.com/taosdata/TDengine.git -cd TDengine -``` + ```bash + git clone https://github.com/taosdata/TDengine.git + cd TDengine + ``` -You can modify the file ~/.gitconfig to use ssh protocol instead of https for better download speed. You will need to upload ssh public key to GitHub first. Please refer to GitHub official documentation for detail. + You can modify the file ~/.gitconfig to use ssh protocol instead of https for better download speed. You will need to upload ssh public key to GitHub first. Please refer to GitHub official documentation for detail. -``` -[url "git@github.com:"] - insteadOf = https://github.com/ -``` + ``` + [url "git@github.com:"] + insteadOf = https://github.com/ + ``` -## 3.3 Special Note - -[JDBC Connector](https://github.com/taosdata/taos-connector-jdbc)， [Go Connector](https://github.com/taosdata/driver-go)，[Python Connector](https://github.com/taosdata/taos-connector-python)，[Node.js Connector](https://github.com/taosdata/taos-connector-node)，[C# Connector](https://github.com/taosdata/taos-connector-dotnet) ，[Rust Connector](https://github.com/taosdata/taos-connector-rust) and [Grafana plugin](https://github.com/taosdata/grafanaplugin) has been moved to standalone repository. +- Special Note + [JDBC Connector](https://github.com/taosdata/taos-connector-jdbc)， [Go Connector](https://github.com/taosdata/driver-go)，[Python Connector](https://github.com/taosdata/taos-connector-python)，[Node.js Connector](https://github.com/taosdata/taos-connector-node)，[C# Connector](https://github.com/taosdata/taos-connector-dotnet) ，[Rust Connector](https://github.com/taosdata/taos-connector-rust) and [Grafana plugin](https://github.com/taosdata/grafanaplugin) has been moved to standalone repository. # 4. Building @@ -217,258 +207,258 @@ TDengine provide a few useful tools such as taosBenchmark (was named taosdemo) a To build TDengine, use [CMake](https://cmake.org/) 3.13.0 or higher versions in the project directory. -Linux platform building +- Linux platform building -You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below: + You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below: -```bash -./build.sh -``` + ```bash + ./build.sh + ``` -It equals to execute following commands: + It equals to execute following commands: -```bash -mkdir debug -cd debug -cmake .. -DBUILD_TOOLS=true -DBUILD_CONTRIB=true -make -``` + ```bash + mkdir debug + cd debug + cmake .. -DBUILD_TOOLS=true -DBUILD_CONTRIB=true + make + ``` -You can use Jemalloc as memory allocator instead of glibc: + You can use Jemalloc as memory allocator instead of glibc: -``` -apt install autoconf -cmake .. -DJEMALLOC_ENABLED=true -``` + ``` + apt install autoconf + cmake .. -DJEMALLOC_ENABLED=true + ``` -TDengine build script can detect the host machine's architecture on X86-64, X86, arm64 platform. -You can also specify CPUTYPE option like aarch64 too if the detection result is not correct: + TDengine build script can detect the host machine's architecture on X86-64, X86, arm64 platform. + You can also specify CPUTYPE option like aarch64 too if the detection result is not correct: -aarch64: + aarch64: -```bash -cmake .. -DCPUTYPE=aarch64 && cmake --build . -``` + ```bash + cmake .. -DCPUTYPE=aarch64 && cmake --build . + ``` -4.2 Windows platform building +- Windows platform building -If you use the Visual Studio 2013, please open a command window by executing "cmd.exe". -Please specify "amd64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. + If you use the Visual Studio 2013, please open a command window by executing "cmd.exe". + Please specify "amd64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. -```cmd -mkdir debug && cd debug -"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" < amd64 | x86 > -cmake .. -G "NMake Makefiles" -nmake -``` + ```cmd + mkdir debug && cd debug + "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" < amd64 | x86 > + cmake .. -G "NMake Makefiles" + nmake + ``` -If you use the Visual Studio 2019 or 2017: + If you use the Visual Studio 2019 or 2017: -please open a command window by executing "cmd.exe". -Please specify "x64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. + please open a command window by executing "cmd.exe". + Please specify "x64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. -```cmd -mkdir debug && cd debug -"c:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" < x64 | x86 > -cmake .. -G "NMake Makefiles" -nmake -``` + ```cmd + mkdir debug && cd debug + "c:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" < x64 | x86 > + cmake .. -G "NMake Makefiles" + nmake + ``` -Or, you can simply open a command window by clicking Windows Start -> "Visual Studio < 2019 | 2017 >" folder -> "x64 Native Tools Command Prompt for VS < 2019 | 2017 >" or "x86 Native Tools Command Prompt for VS < 2019 | 2017 >" depends what architecture your Windows is, then execute commands as follows: + Or, you can simply open a command window by clicking Windows Start -> "Visual Studio < 2019 | 2017 >" folder -> "x64 Native Tools Command Prompt for VS < 2019 | 2017 >" or "x86 Native Tools Command Prompt for VS < 2019 | 2017 >" depends what architecture your Windows is, then execute commands as follows: -```cmd -mkdir debug && cd debug -cmake .. -G "NMake Makefiles" -nmake -``` + ```cmd + mkdir debug && cd debug + cmake .. -G "NMake Makefiles" + nmake + ``` -MacOS platform building +- MacOS platform building -Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur. + Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur. -```shell -mkdir debug && cd debug -cmake .. && cmake --build . -``` + ```shell + mkdir debug && cd debug + cmake .. && cmake --build . + ``` # 5. Packaging -Linux platform packaging - -to be updated... - -Windows platform packaging - -to be updated... - -MacOS platform packaging - -to be updated... +To be updated... # 6. Installation -Linux platform installation +- Linux platform installation -After building successfully, TDengine can be installed by + After building successfully, TDengine can be installed by -```bash -sudo make install -``` + ```bash + sudo make install + ``` -Users can find more information about directories installed on the system in the [directory and files](https://docs.tdengine.com/reference/directory/) section. + Users can find more information about directories installed on the system in the [directory and files](https://docs.tdengine.com/reference/directory/) section. -Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/deploy-from-package/) for it. + Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/deploy-from-package/) for it. -Windows platform installation +- Windows platform installation -After building successfully, TDengine can be installed by: + After building successfully, TDengine can be installed by: -```cmd -nmake install -``` + ```cmd + nmake install + ``` -MacOS platform installation +- MacOS platform installation -After building successfully, TDengine can be installed by: + After building successfully, TDengine can be installed by: -```bash -sudo make install -``` + ```bash + sudo make install + ``` # 7. Running -To start the service after installation on linux, in a terminal, use: +- To start the service after installation on linux, in a terminal, use: -```bash -sudo systemctl start taosd -``` + ```bash + sudo systemctl start taosd + ``` -Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: + Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: -```bash -taos -``` + ```bash + taos + ``` -If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. + If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. -If you don't want to run TDengine as a service, you can run it in current shell. For example, to quickly start a TDengine server after building, run the command below in terminal: (We take Linux as an example, command on Windows will be `taosd.exe`) + If you don't want to run TDengine as a service, you can run it in current shell. For example, to quickly start a TDengine server after building, run the command below in terminal: (We take Linux as an example, command on Windows will be `taosd.exe`) -```bash -./build/bin/taosd -c test/cfg -``` + ```bash + ./build/bin/taosd -c test/cfg + ``` -In another terminal, use the TDengine CLI to connect the server: + In another terminal, use the TDengine CLI to connect the server: -```bash -./build/bin/taos -c test/cfg -``` + ```bash + ./build/bin/taos -c test/cfg + ``` -option "-c test/cfg" specifies the system configuration file directory. + option "-c test/cfg" specifies the system configuration file directory. -To start the service after installation on windows, in a terminal, use: +- To start the service after installation on windows, in a terminal, use: -```bash -to be updated -``` -Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: + ```bash + to be updated + ``` + Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: -```bash -to be updated -``` + ```bash + to be updated + ``` -To start the service after installation on macOS, double-click the /applications/TDengine to start the program, or in a terminal, use: +- To start the service after installation on macOS, double-click the /applications/TDengine to start the program, or in a terminal, use: -```bash -sudo launchctl start com.tdengine.taosd -``` + ```bash + sudo launchctl start com.tdengine.taosd + ``` -Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: + Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: -```bash -taos -``` + ```bash + taos + ``` If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. # 8. Testing -## 8.1 Run the TSIM test script +- Run the TSIM test script -TSIM test framework is developed by c++ in the start-up period of TDengine， the test scripts are basic cases, you can run -the script with below command: + TSIM test framework is developed by c++ in the start-up period of TDengine， the test scripts are basic cases, you can run + the script with below command: -```bash -cd /root/TDengine/tests/script -./test.sh -f tsim/db/basic1.sim -``` + ```bash + cd /root/TDengine/tests/script + ./test.sh -f tsim/db/basic1.sim + ``` -## 8.2 Run the Python test script -Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only -work for TDengine enterprise version, you can run the script with below command: +- Run the Python test script + + Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only + work for TDengine enterprise version, you can run the script with below command: -```bash -cd /root/TDengine/tests/system-test -python3 ./test.py -f 2-query/floor.py -``` + ```bash + cd /root/TDengine/tests/system-test + python3 ./test.py -f 2-query/floor.py + ``` -## 8.3 Run unittest -Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run -the script with below command: +- Run unittest + + Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run + the script with below command: -```bash -cd /root/TDengine/tests/unit-test/ -bash test.sh -``` + ```bash + cd /root/TDengine/tests/unit-test/ + bash test.sh + ``` -## 8.4 Smoke Testing -Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine, you can run the -script with below command: +- Smoke Testing + + Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine, you can run the + script with below command: -```bash -cd /root/TDengine/packaging/smokeTest -./test_smoking_selfhost.sh -``` + ```bash + cd /root/TDengine/packaging/smokeTest + ./test_smoking_selfhost.sh + ``` -## 8.5 TSBS Test --replace -The Time Series Benchmark Suite(TSBS) test script provides a standardized approach to evaluate the performance of various -time series databases, you can run the script with below command: +- TSBS Test --replace -1. Clone the code -```bash -cd /root && git clone https://github.com/taosdata/tsbs.git && cd tsbs/scripts/tsdbComp -``` -1. Modify IP and host of client and server in `test.ini` -```ini -clientIP="192.168.0.203" # client ip -clientHost="trd03" # client hostname -serverIP="192.168.0.204" # server ip -serverHost="trd04" # server hostname -``` -1. Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: -```ini -serverPass="taosdata123" # server root password -``` -1. Run the following command to start the test: - ```bash -nohup bash tsdbComparison.sh > test.log & -``` -1. When the test is done, the result can be found in `/data2/` directory, which can also be configured in `test.ini`. + The Time Series Benchmark Suite(TSBS) test script provides a standardized approach to evaluate the performance of various + time series databases, you can run the script with below command: -## 8.6 Crash_gen Test -Crash_gen is a chaotic testing tool developed by TDengine, it can evaluate the resilience of TDengine through simulating -normal operation、intentional fault injection and their combination, you can run the script with below command: + - Clone the code -```bash -cd /root/TDengine/tests/pytest/ && ./crash_gen.sh -``` + ```bash + cd /root && git clone https://github.com/taosdata/tsbs.git && cd tsbs/scripts/tsdbComp + ``` + + - Modify IP and host of client and server in `test.ini` + ```ini + clientIP="192.168.0.203" # client ip + clientHost="trd03" # client hostname + serverIP="192.168.0.204" # server ip + serverHost="trd04" # server hostname + ``` + + - Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: + + ```ini + serverPass="taosdata123" # server root password + ``` + + - Run the following command to start the test: + ```bash + nohup bash tsdbComparison.sh > test.log & + ``` + When the test is done, the result can be found in `/data2/` directory, which can also be configured in `test.ini`. + +- Crash_gen Test + + Crash_gen is a chaotic testing tool developed by TDengine, it can evaluate the resilience of TDengine through simulating + normal operation、intentional fault injection and their combination, you can run the script with below command: + + ```bash + cd /root/TDengine/tests/pytest/ && ./crash_gen.sh + ``` Windows platform testing -to be updated... + to be updated... MacOS platform testing -to be updated... + to be updated... # 9. Releasing From 7ac75a8dba6ffbe01c335a16ce8c8e0900166f15 Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Tue, 7 Jan 2025 18:18:14 +0800 Subject: [PATCH 05/56] Update toc --- README.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index d843f98ffa..30d8f21d88 100644 --- a/README.md +++ b/README.md @@ -26,19 +26,18 @@ English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine # Table of Contents -- [Table of Contents](#table-of-contents) -- [1. Introduction](#1-introduction) -- [2. Documentation](#2-documentation) -- [3. Prerequisites](#3-prerequisites) -- [4. Building](#4-building) -- [5. Packaging](#5-packaging) -- [6. Installation](#6-installation) -- [7. Running](#7-running) -- [8. Testing](#8-testing) -- [9. Releasing](#9-releasing) -- [10. CI/CD](#10-cicd) -- [11. Coverage --replace](#11-coverage---replace) -- [12. Contributing](#12-contributing) +1. [Introduction](#1-introduction) +1. [Documentation](#2-documentation) +1. [Prerequisites](#3-prerequisites) +1. [Building](#4-building) +1. [Packaging](#5-packaging) +1. [Installation](#6-installation) +1. [Running](#7-running) +1. [Testing](#8-testing) +1. [Releasing](#9-releasing) +1. [CI/CD](#10-cicd) +1. [Coverage --replace](#11-coverage---replace) +1. [Contributing](#12-contributing) # 1. Introduction From c85f5833a0742fb74179db1fd98ad61dda602f3c Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Wed, 8 Jan 2025 08:18:39 +0800 Subject: [PATCH 06/56] adjust the contents style format by charles --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 30d8f21d88..fc938942d6 100644 --- a/README.md +++ b/README.md @@ -65,13 +65,13 @@ For user manual, system design and architecture, please refer to [TDengine Docum List the software and tools required to work on the project. -- go 1.20+ (for taosadapter) -- node 16.20.2 (for taos-explorer) -- python 3.10.12+ (for test) + - go 1.20+ (for taosadapter) + - node 16.20.2 (for taos-explorer) + - python 3.10.12+ (for test) Step-by-step instructions to set up the prerequisites software. -- Install dependencies tools +#### Install dependencies tools - The required package for linux @@ -177,7 +177,7 @@ Step-by-step instructions to set up the prerequisites software. brew install argp-standalone gflags pkgconfig ``` -- Get the source codes +#### Get the source codes First of all, you may clone the source codes from github: @@ -193,7 +193,7 @@ Step-by-step instructions to set up the prerequisites software. insteadOf = https://github.com/ ``` -- Special Note +#### Special Note [JDBC Connector](https://github.com/taosdata/taos-connector-jdbc)， [Go Connector](https://github.com/taosdata/driver-go)，[Python Connector](https://github.com/taosdata/taos-connector-python)，[Node.js Connector](https://github.com/taosdata/taos-connector-node)，[C# Connector](https://github.com/taosdata/taos-connector-dotnet) ，[Rust Connector](https://github.com/taosdata/taos-connector-rust) and [Grafana plugin](https://github.com/taosdata/grafanaplugin) has been moved to standalone repository. # 4. Building @@ -416,13 +416,13 @@ If TDengine CLI connects the server successfully, welcome messages and version i The Time Series Benchmark Suite(TSBS) test script provides a standardized approach to evaluate the performance of various time series databases, you can run the script with below command: - - Clone the code + Clone the code ```bash cd /root && git clone https://github.com/taosdata/tsbs.git && cd tsbs/scripts/tsdbComp ``` - - Modify IP and host of client and server in `test.ini` + Modify IP and host of client and server in `test.ini` ```ini clientIP="192.168.0.203" # client ip clientHost="trd03" # client hostname @@ -430,13 +430,13 @@ If TDengine CLI connects the server successfully, welcome messages and version i serverHost="trd04" # server hostname ``` - - Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: + Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: ```ini serverPass="taosdata123" # server root password ``` - - Run the following command to start the test: + Run the following command to start the test: ```bash nohup bash tsdbComparison.sh > test.log & ``` @@ -472,8 +472,8 @@ cd /root/TDengine/tests ``` # 11. Coverage --replace -We can see coverage result in https://coveralls.io/github/taosdata/TDengine -We can also run coverage script locally. +You can see coverage result in https://coveralls.io/github/taosdata/TDengine +You can also run coverage script locally. ```bash cd /root/TDengine/tests From a0be3dcaec62f73088b09423dff8823530b0b1bc Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Wed, 8 Jan 2025 10:40:06 +0800 Subject: [PATCH 07/56] update README to add child section number and remove tsbs, crash_gen test from testing part --- README.md | 459 ++++++++++++++++++++---------------------------------- 1 file changed, 165 insertions(+), 294 deletions(-) diff --git a/README.md b/README.md index fc938942d6..8c5ec10df2 100644 --- a/README.md +++ b/README.md @@ -63,138 +63,42 @@ For user manual, system design and architecture, please refer to [TDengine Docum # 3. Prerequisites -List the software and tools required to work on the project. +## 3.1 Install dependencies tools - - go 1.20+ (for taosadapter) - - node 16.20.2 (for taos-explorer) - - python 3.10.12+ (for test) +### The required package for linux -Step-by-step instructions to set up the prerequisites software. +```bash +apt-get install -y llvm gcc make cmake libssl-dev pkg-config perl g++ lzma curl locales psmisc sudo tree libgeos-dev libgflags2.2 libgflags-dev libgoogle-glog-dev libjansson-dev libsnappy-dev liblzma-dev libz-dev zlib1g build-essential valgrind rsync vim libjemalloc-dev openssh-server screen sshpass net-tools dirmngr gnupg apt-transport-https ca-certificates software-properties-common r-base iputils-ping +``` -#### Install dependencies tools +### The required package for windows - - The required package for linux +to be updated... - ```bash - apt-get install -y llvm gcc make cmake libssl-dev pkg-config perl g++ lzma curl locales psmisc sudo tree libgeos-dev libgflags2.2 libgflags-dev libgoogle-glog-dev libjansson-dev libsnappy-dev liblzma-dev libz-dev zlib1g build-essential valgrind rsync vim libjemalloc-dev openssh-server screen sshpass net-tools dirmngr gnupg apt-transport-https ca-certificates software-properties-common r-base iputils-ping - ``` +### The required package for macOS - Install Go for linux +``` +brew install argp-standalone gflags pkgconfig +``` - Update the installation package to version 1.23.3. +## 3.2 Get the source codes - ```bash - cd /usr/local/ - wget https://golang.google.cn/dl/go1.23.3.linux-amd64.tar.gz - rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.3.linux-amd64.tar.gz - ``` +First of all, you may clone the source codes from github: - Set up environment variables, first add the following content to the end of the `~/.bashrc` file. +```bash +git clone https://github.com/taosdata/TDengine.git +cd TDengine +``` - ```bash - export GO_HOME=/usr/local/go - export PATH=$GO_HOME/bin:$PATH - export CGO_ENABLED=1 - ``` +You can modify the file ~/.gitconfig to use ssh protocol instead of https for better download speed. You will need to upload ssh public key to GitHub first. Please refer to GitHub official documentation for detail. - Then make the environment variables take effect. +``` +[url "git@github.com:"] + insteadOf = https://github.com/ +``` - ```bash - source ~/.bashrc - ``` - - Configure proxy to accelerate the download of Go dependencies. - - ```bash - go env -w GOPROXY=https://goproxy.cn,direct - go env -w GO111MODULE=on - ``` - - Check if the environment variables have taken effect and if the version is the installed version. - - ```bash - go env - go version - ``` - - Install node for linux - - Recommend install node using nvm. - - ```bash - curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash - ``` - - Set up environment variables, add the following content to the end of the `~/.bashrc` file. - - ```bash - export NVM_DIR="$HOME/.nvm" - [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" - ``` - - Then make the environment variables take effect. - - ```bash - source ~/.bashrc - ``` - - Finally, Install node and yarn. - - ```bash - nvm install 16.20.2 - npm config set registry=https://registry.npmmirror.com - npm install -g yarn - ``` - - Install Python-connector for linux - - Install Python3. - - ```bash - apt install python3 - apt install python3-pip - ``` - - Install the dependent Python components. - - ```bash - pip3 install pandas psutil fabric2 requests faker simplejson toml pexpect tzlocal distro decorator loguru hyperloglog - ``` - - Install the Python connector for TDengine. - - ```bash - pip3 install taospy taos-ws-py - ``` - - - The required package for windows - - to be updated... - - - The required package for macOS - - ``` - brew install argp-standalone gflags pkgconfig - ``` - -#### Get the source codes - - First of all, you may clone the source codes from github: - - ```bash - git clone https://github.com/taosdata/TDengine.git - cd TDengine - ``` - - You can modify the file ~/.gitconfig to use ssh protocol instead of https for better download speed. You will need to upload ssh public key to GitHub first. Please refer to GitHub official documentation for detail. - - ``` - [url "git@github.com:"] - insteadOf = https://github.com/ - ``` - -#### Special Note - [JDBC Connector](https://github.com/taosdata/taos-connector-jdbc)， [Go Connector](https://github.com/taosdata/driver-go)，[Python Connector](https://github.com/taosdata/taos-connector-python)，[Node.js Connector](https://github.com/taosdata/taos-connector-node)，[C# Connector](https://github.com/taosdata/taos-connector-dotnet) ，[Rust Connector](https://github.com/taosdata/taos-connector-rust) and [Grafana plugin](https://github.com/taosdata/grafanaplugin) has been moved to standalone repository. +## 3.3 Special Note +[JDBC Connector](https://github.com/taosdata/taos-connector-jdbc)， [Go Connector](https://github.com/taosdata/driver-go)，[Python Connector](https://github.com/taosdata/taos-connector-python)，[Node.js Connector](https://github.com/taosdata/taos-connector-node)，[C# Connector](https://github.com/taosdata/taos-connector-dotnet) ，[Rust Connector](https://github.com/taosdata/taos-connector-rust) and [Grafana plugin](https://github.com/taosdata/grafanaplugin) has been moved to standalone repository. # 4. Building @@ -206,79 +110,79 @@ TDengine provide a few useful tools such as taosBenchmark (was named taosdemo) a To build TDengine, use [CMake](https://cmake.org/) 3.13.0 or higher versions in the project directory. -- Linux platform building +## 4.1 Linux platform building - You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below: +You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below: - ```bash - ./build.sh - ``` +```bash +./build.sh +``` - It equals to execute following commands: +It equals to execute following commands: - ```bash - mkdir debug - cd debug - cmake .. -DBUILD_TOOLS=true -DBUILD_CONTRIB=true - make - ``` +```bash +mkdir debug +cd debug +cmake .. -DBUILD_TOOLS=true -DBUILD_CONTRIB=true +make +``` - You can use Jemalloc as memory allocator instead of glibc: +You can use Jemalloc as memory allocator instead of glibc: - ``` - apt install autoconf - cmake .. -DJEMALLOC_ENABLED=true - ``` +``` +apt install autoconf +cmake .. -DJEMALLOC_ENABLED=true +``` - TDengine build script can detect the host machine's architecture on X86-64, X86, arm64 platform. - You can also specify CPUTYPE option like aarch64 too if the detection result is not correct: +TDengine build script can detect the host machine's architecture on X86-64, X86, arm64 platform. +You can also specify CPUTYPE option like aarch64 too if the detection result is not correct: - aarch64: +aarch64: - ```bash - cmake .. -DCPUTYPE=aarch64 && cmake --build . - ``` +```bash +cmake .. -DCPUTYPE=aarch64 && cmake --build . +``` -- Windows platform building +## 4.2 Windows platform building - If you use the Visual Studio 2013, please open a command window by executing "cmd.exe". - Please specify "amd64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. +If you use the Visual Studio 2013, please open a command window by executing "cmd.exe". +Please specify "amd64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. - ```cmd - mkdir debug && cd debug - "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" < amd64 | x86 > - cmake .. -G "NMake Makefiles" - nmake - ``` +```cmd +mkdir debug && cd debug +"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" < amd64 | x86 > +cmake .. -G "NMake Makefiles" +nmake +``` - If you use the Visual Studio 2019 or 2017: +If you use the Visual Studio 2019 or 2017: - please open a command window by executing "cmd.exe". - Please specify "x64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. +please open a command window by executing "cmd.exe". +Please specify "x64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. - ```cmd - mkdir debug && cd debug - "c:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" < x64 | x86 > - cmake .. -G "NMake Makefiles" - nmake - ``` +```cmd +mkdir debug && cd debug +"c:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" < x64 | x86 > +cmake .. -G "NMake Makefiles" +nmake +``` - Or, you can simply open a command window by clicking Windows Start -> "Visual Studio < 2019 | 2017 >" folder -> "x64 Native Tools Command Prompt for VS < 2019 | 2017 >" or "x86 Native Tools Command Prompt for VS < 2019 | 2017 >" depends what architecture your Windows is, then execute commands as follows: +Or, you can simply open a command window by clicking Windows Start -> "Visual Studio < 2019 | 2017 >" folder -> "x64 Native Tools Command Prompt for VS < 2019 | 2017 >" or "x86 Native Tools Command Prompt for VS < 2019 | 2017 >" depends what architecture your Windows is, then execute commands as follows: - ```cmd - mkdir debug && cd debug - cmake .. -G "NMake Makefiles" - nmake - ``` +```cmd +mkdir debug && cd debug +cmake .. -G "NMake Makefiles" +nmake +``` -- MacOS platform building +## 4.3 MacOS platform building - Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur. +Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur. - ```shell - mkdir debug && cd debug - cmake .. && cmake --build . - ``` +```shell +mkdir debug && cd debug +cmake .. && cmake --build . +``` # 5. Packaging @@ -286,176 +190,143 @@ To be updated... # 6. Installation -- Linux platform installation +## 6.1 Linux platform installation - After building successfully, TDengine can be installed by +After building successfully, TDengine can be installed by - ```bash - sudo make install - ``` +```bash +sudo make install +``` - Users can find more information about directories installed on the system in the [directory and files](https://docs.tdengine.com/reference/directory/) section. +Users can find more information about directories installed on the system in the [directory and files](https://docs.tdengine.com/reference/directory/) section. - Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/deploy-from-package/) for it. +Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/deploy-from-package/) for it. -- Windows platform installation +## 6.2 Windows platform installation - After building successfully, TDengine can be installed by: +After building successfully, TDengine can be installed by: - ```cmd - nmake install - ``` +```cmd +nmake install +``` -- MacOS platform installation +## 6.3 MacOS platform installation - After building successfully, TDengine can be installed by: +After building successfully, TDengine can be installed by: - ```bash - sudo make install - ``` +```bash +sudo make install +``` # 7. Running -- To start the service after installation on linux, in a terminal, use: +## 7.1 Run TDengine on linux - ```bash - sudo systemctl start taosd - ``` +To start the service after installation on linux, in a terminal, use: - Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: +```bash +sudo systemctl start taosd +``` - ```bash - taos - ``` +Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: - If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. +```bash +taos +``` - If you don't want to run TDengine as a service, you can run it in current shell. For example, to quickly start a TDengine server after building, run the command below in terminal: (We take Linux as an example, command on Windows will be `taosd.exe`) +If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. - ```bash - ./build/bin/taosd -c test/cfg - ``` +If you don't want to run TDengine as a service, you can run it in current shell. For example, to quickly start a TDengine server after building, run the command below in terminal: (We take Linux as an example, command on Windows will be `taosd.exe`) - In another terminal, use the TDengine CLI to connect the server: +```bash +./build/bin/taosd -c test/cfg +``` - ```bash - ./build/bin/taos -c test/cfg - ``` +In another terminal, use the TDengine CLI to connect the server: - option "-c test/cfg" specifies the system configuration file directory. +```bash +./build/bin/taos -c test/cfg +``` -- To start the service after installation on windows, in a terminal, use: +option "-c test/cfg" specifies the system configuration file directory. - ```bash - to be updated - ``` - Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: +## 7.2 Run TDengine on windows - ```bash - to be updated - ``` +To start the service after installation on windows, in a terminal, use: -- To start the service after installation on macOS, double-click the /applications/TDengine to start the program, or in a terminal, use: +```bash +to be updated +``` - ```bash - sudo launchctl start com.tdengine.taosd - ``` +Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: - Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: +```bash +taos +``` - ```bash - taos - ``` +## 7.3 Run TDengine on MacOS + +To start the service after installation on macOS, double-click the /applications/TDengine to start the program, or in a terminal, use: + +```bash +sudo launchctl start com.tdengine.taosd +``` + +Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: + +```bash +taos +``` If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. # 8. Testing -- Run the TSIM test script +## 8.1 Run the TSIM test script - TSIM test framework is developed by c++ in the start-up period of TDengine， the test scripts are basic cases, you can run - the script with below command: +TSIM test framework is developed by c++ in the start-up period of TDengine， the test scripts are basic cases, you can run +the script with below command: - ```bash - cd /root/TDengine/tests/script - ./test.sh -f tsim/db/basic1.sim - ``` +```bash +cd /root/TDengine/tests/script +./test.sh -f tsim/db/basic1.sim +``` -- Run the Python test script - - Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only - work for TDengine enterprise version, you can run the script with below command: +## 8.2 Run the Python test script - ```bash - cd /root/TDengine/tests/system-test - python3 ./test.py -f 2-query/floor.py - ``` +Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only +work for TDengine enterprise version, you can run the script with below command: -- Run unittest - - Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run - the script with below command: +```bash +cd /root/TDengine/tests/system-test +python3 ./test.py -f 2-query/floor.py +``` - ```bash - cd /root/TDengine/tests/unit-test/ - bash test.sh - ``` +## 8.3 Run unittest -- Smoke Testing - - Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine, you can run the - script with below command: +Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run +the script with below command: - ```bash - cd /root/TDengine/packaging/smokeTest - ./test_smoking_selfhost.sh - ``` +```bash +cd /root/TDengine/tests/unit-test/ +bash test.sh +``` -- TSBS Test --replace +## 8.4 Smoke Testing - The Time Series Benchmark Suite(TSBS) test script provides a standardized approach to evaluate the performance of various - time series databases, you can run the script with below command: +Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine, you can run the +script with below command: - Clone the code +```bash +cd /root/TDengine/packaging/smokeTest +./test_smoking_selfhost.sh +``` - ```bash - cd /root && git clone https://github.com/taosdata/tsbs.git && cd tsbs/scripts/tsdbComp - ``` - - Modify IP and host of client and server in `test.ini` - ```ini - clientIP="192.168.0.203" # client ip - clientHost="trd03" # client hostname - serverIP="192.168.0.204" # server ip - serverHost="trd04" # server hostname - ``` - - Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: - - ```ini - serverPass="taosdata123" # server root password - ``` - - Run the following command to start the test: - ```bash - nohup bash tsdbComparison.sh > test.log & - ``` - When the test is done, the result can be found in `/data2/` directory, which can also be configured in `test.ini`. - -- Crash_gen Test - - Crash_gen is a chaotic testing tool developed by TDengine, it can evaluate the resilience of TDengine through simulating - normal operation、intentional fault injection and their combination, you can run the script with below command: - - ```bash - cd /root/TDengine/tests/pytest/ && ./crash_gen.sh - ``` - -Windows platform testing +## Windows platform testing to be updated... -MacOS platform testing +## MacOS platform testing to be updated... From abbc6416328b44ce8d1d2de33e34b513191be5b5 Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Wed, 8 Jan 2025 18:49:24 +0800 Subject: [PATCH 08/56] docs: refactor readme --- README.md | 203 +++++++++++++++++++----------------------------- tests/README.md | 43 ++++++++++ 2 files changed, 124 insertions(+), 122 deletions(-) create mode 100644 tests/README.md diff --git a/README.md b/README.md index 8c5ec10df2..5fadbd22d8 100644 --- a/README.md +++ b/README.md @@ -30,14 +30,13 @@ English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine 1. [Documentation](#2-documentation) 1. [Prerequisites](#3-prerequisites) 1. [Building](#4-building) -1. [Packaging](#5-packaging) -1. [Installation](#6-installation) -1. [Running](#7-running) -1. [Testing](#8-testing) -1. [Releasing](#9-releasing) -1. [CI/CD](#10-cicd) -1. [Coverage --replace](#11-coverage---replace) -1. [Contributing](#12-contributing) +1. [Installation](#5-installation) +1. [Running](#6-running) +1. [Testing](#7-testing) +1. [Releasing](#8-releasing) +1. [CI/CD](#9-cicd) +1. [Coverage](#10-coverage) +1. [Contributing](#11-contributing) # 1. Introduction @@ -63,42 +62,49 @@ For user manual, system design and architecture, please refer to [TDengine Docum # 3. Prerequisites -## 3.1 Install dependencies tools +## 3.1 On Linux -### The required package for linux +### For Ubuntu 18.04 or Later ```bash -apt-get install -y llvm gcc make cmake libssl-dev pkg-config perl g++ lzma curl locales psmisc sudo tree libgeos-dev libgflags2.2 libgflags-dev libgoogle-glog-dev libjansson-dev libsnappy-dev liblzma-dev libz-dev zlib1g build-essential valgrind rsync vim libjemalloc-dev openssh-server screen sshpass net-tools dirmngr gnupg apt-transport-https ca-certificates software-properties-common r-base iputils-ping -``` - -### The required package for windows - -to be updated... - -### The required package for macOS ``` + +### For CentOS 7 + +```bash + +``` + +### For Fedora or Rocky Linux + +```bash + +``` + +## 3.2 On macOS + +Please intall the dependencies with [brew](https://brew.sh/). + +```bash brew install argp-standalone gflags pkgconfig ``` -## 3.2 Get the source codes +## 3.3 On Windows -First of all, you may clone the source codes from github: +Work in Progress. + +## 3.4 Clone the repo + +Clone the repository to the target machine: ```bash git clone https://github.com/taosdata/TDengine.git cd TDengine ``` -You can modify the file ~/.gitconfig to use ssh protocol instead of https for better download speed. You will need to upload ssh public key to GitHub first. Please refer to GitHub official documentation for detail. - -``` -[url "git@github.com:"] - insteadOf = https://github.com/ -``` - -## 3.3 Special Note -[JDBC Connector](https://github.com/taosdata/taos-connector-jdbc)， [Go Connector](https://github.com/taosdata/driver-go)，[Python Connector](https://github.com/taosdata/taos-connector-python)，[Node.js Connector](https://github.com/taosdata/taos-connector-node)，[C# Connector](https://github.com/taosdata/taos-connector-dotnet) ，[Rust Connector](https://github.com/taosdata/taos-connector-rust) and [Grafana plugin](https://github.com/taosdata/grafanaplugin) has been moved to standalone repository. +> [!NOTE] +> TDengine Connectors can be found in following repositories: [JDBC Connector](https://github.com/taosdata/taos-connector-jdbc), [Go Connector](https://github.com/taosdata/driver-go), [Python Connector](https://github.com/taosdata/taos-connector-python), [Node.js Connector](https://github.com/taosdata/taos-connector-node), [C# Connector](https://github.com/taosdata/taos-connector-dotnet), [Rust Connector](https://github.com/taosdata/taos-connector-rust). # 4. Building @@ -110,7 +116,7 @@ TDengine provide a few useful tools such as taosBenchmark (was named taosdemo) a To build TDengine, use [CMake](https://cmake.org/) 3.13.0 or higher versions in the project directory. -## 4.1 Linux platform building +## 4.1 Build on Linux You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below: @@ -129,7 +135,7 @@ make You can use Jemalloc as memory allocator instead of glibc: -``` +```bash apt install autoconf cmake .. -DJEMALLOC_ENABLED=true ``` @@ -143,7 +149,16 @@ aarch64: cmake .. -DCPUTYPE=aarch64 && cmake --build . ``` -## 4.2 Windows platform building +## 4.2 Build on macOS + +Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur. + +```shell +mkdir debug && cd debug +cmake .. && cmake --build . +``` + +## 4.3 Build on Windows If you use the Visual Studio 2013, please open a command window by executing "cmd.exe". Please specify "amd64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. @@ -175,22 +190,9 @@ cmake .. -G "NMake Makefiles" nmake ``` -## 4.3 MacOS platform building +# 5. Installation -Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur. - -```shell -mkdir debug && cd debug -cmake .. && cmake --build . -``` - -# 5. Packaging - -To be updated... - -# 6. Installation - -## 6.1 Linux platform installation +## 5.1 Install on Linux After building successfully, TDengine can be installed by @@ -202,15 +204,7 @@ Users can find more information about directories installed on the system in the Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/deploy-from-package/) for it. -## 6.2 Windows platform installation - -After building successfully, TDengine can be installed by: - -```cmd -nmake install -``` - -## 6.3 MacOS platform installation +## 5.2 Install on macOS After building successfully, TDengine can be installed by: @@ -218,9 +212,17 @@ After building successfully, TDengine can be installed by: sudo make install ``` -# 7. Running +## 5.3 Install on Windows -## 7.1 Run TDengine on linux +After building successfully, TDengine can be installed by: + +```cmd +nmake install +``` + +# 6. Running + +## 6.1 Run TDengine on Linux To start the service after installation on linux, in a terminal, use: @@ -250,9 +252,9 @@ In another terminal, use the TDengine CLI to connect the server: option "-c test/cfg" specifies the system configuration file directory. -## 7.2 Run TDengine on windows +## 6.2 Run TDengine on Windows -To start the service after installation on windows, in a terminal, use: +To start the service after installation on Windows, in a terminal, use: ```bash to be updated @@ -264,7 +266,7 @@ Then users can use the TDengine CLI to connect the TDengine server. In a termina taos ``` -## 7.3 Run TDengine on MacOS +## 6.3 Run TDengine on macOS To start the service after installation on macOS, double-click the /applications/TDengine to start the program, or in a terminal, use: @@ -280,77 +282,34 @@ taos If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. -# 8. Testing +# 7. Testing -## 8.1 Run the TSIM test script +For how to run different types of tests on TDengine, please see [Testing TDengine](./tests/README.md). -TSIM test framework is developed by c++ in the start-up period of TDengine， the test scripts are basic cases, you can run -the script with below command: +# 8. Releasing + +For the complete list of TDengine Releases, please see [Releases](https://github.com/taosdata/TDengine/releases). + +# 9. CI/CD + +Now, Jenkins is mainly used to build CI/CD pipeline for TDengine. To run the tests in the CI/CD pipeline, please run following commands: ```bash -cd /root/TDengine/tests/script -./test.sh -f tsim/db/basic1.sim +cd tests +./run_all_ci_cases.sh -b main # on main branch ``` -## 8.2 Run the Python test script +TDengine build check workflow can be found in this [Github Action](https://github.com/taosdata/TDengine/actions/workflows/taosd-ci-build.yml). -Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only -work for TDengine enterprise version, you can run the script with below command: +# 10. Coverage + +Latest TDengine test coverage report can be found on [coveralls.io](https://coveralls.io/github/taosdata/TDengine). To create the test coverage report (in HTML format) locally, please run following commands: ```bash -cd /root/TDengine/tests/system-test -python3 ./test.py -f 2-query/floor.py -``` - -## 8.3 Run unittest - -Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run -the script with below command: - -```bash -cd /root/TDengine/tests/unit-test/ -bash test.sh -``` - -## 8.4 Smoke Testing - -Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine, you can run the -script with below command: - -```bash -cd /root/TDengine/packaging/smokeTest -./test_smoking_selfhost.sh -``` - -## Windows platform testing - - to be updated... - -## MacOS platform testing - - to be updated... - -# 9. Releasing - -You can access the [Release](https://github.com/taosdata/TDengine/releases) for TDengine release version list. - -# 10. CI/CD -You can run ci script locally with below commands: - -```bash -cd /root/TDengine/tests -./run_all_ci_cases.sh -b main -``` - -# 11. Coverage --replace -You can see coverage result in https://coveralls.io/github/taosdata/TDengine -You can also run coverage script locally. - -```bash -cd /root/TDengine/tests +cd tests ./run_local_coverage.sh ``` -# 12. Contributing +# 11. Contributing -Please follow the [contribution guidelines](CONTRIBUTING.md) to contribute to the project. +Please follow the [contribution guidelines](CONTRIBUTING.md) to contribute to TDengine. diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000000..55e6688a8f --- /dev/null +++ b/tests/README.md @@ -0,0 +1,43 @@ +# Testing TDengine + +## Unit Test + +Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run +the script with below command: + +```bash +cd tests/unit-test/ +bash test.sh +``` + +## System Test + +Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only +work for TDengine enterprise version, you can run the script with below command: + +```bash +cd tests/system-test +python3 ./test.py -f 2-query/floor.py +``` + +## Smoke Test + +Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine, you can run the +script with commands below: + +```bash +cd /root/TDengine/packaging/smokeTest +./test_smoking_selfhost.sh +``` + +## Legacy Test + +In the early stage of TDengine development, test cases are run by an internal test framework called TSIM, which is developed in C++. To run the legacy test cases, please execute the following commands: + +```bash +cd tests/script +./test.sh -f tsim/db/basic1.sim +``` + + + From a100d96ef3395ab7b890394f3b9eac66f7303ace Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Wed, 8 Jan 2025 19:44:56 +0800 Subject: [PATCH 09/56] docs: collaps different platforms --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 5fadbd22d8..91bcd40f55 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,10 @@ To build TDengine, use [CMake](https://cmake.org/) 3.13.0 or higher versions in ## 4.1 Build on Linux +
+ +Detailed steps to build on Linux + You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below: ```bash @@ -149,8 +153,14 @@ aarch64: cmake .. -DCPUTYPE=aarch64 && cmake --build . ``` +
+ ## 4.2 Build on macOS +
+ +Detailed steps to build on macOS + Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur. ```shell @@ -158,8 +168,14 @@ mkdir debug && cd debug cmake .. && cmake --build . ``` +
+ ## 4.3 Build on Windows +
+ +Detailed steps to build on Windows + If you use the Visual Studio 2013, please open a command window by executing "cmd.exe". Please specify "amd64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat. @@ -189,6 +205,7 @@ mkdir debug && cd debug cmake .. -G "NMake Makefiles" nmake ``` +
# 5. Installation From 7c1363f34c22f8638118ad095764968a09faf0a4 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Thu, 9 Jan 2025 17:30:04 +0800 Subject: [PATCH 10/56] update README and test/README by charles --- README.md | 36 +++++++++++++++++++++++++----------- tests/README.md | 21 +++++++++++++++++++++ 2 files changed, 46 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 91bcd40f55..953bb7c6b1 100644 --- a/README.md +++ b/README.md @@ -67,19 +67,32 @@ For user manual, system design and architecture, please refer to [TDengine Docum ### For Ubuntu 18.04 or Later ```bash - +sudo apt-get udpate +sudo apt-get install -y gcc cmake build-essential git libjansson-dev libsnappy-dev liblzma-dev zlib1g-dev pkg-config ``` -### For CentOS 7 +### For CentOS 8 ```bash - +sudo yum update +yum install -y epel-release gcc gcc-c++ make cmake git perl dnf-plugins-core +yum config-manager --set-enabled powertools +yum install -y zlib-static xz-devel snappy-devel jansson-devel pkgconfig ``` ### For Fedora or Rocky Linux ```bash +sudo dnf install -y gcc gcc-c++ make cmake git perl +sudo dnf install -y zlib-devel xz-devel snappy-devel jansson-devel pkgconfig +``` +To build the [taosTools](https://github.com/taosdata/taos-tools) on Fedora or Rocky, the following packages need to be installed. + +```bash +sudo dnf install -y dnf-plugins-core +sudo dnf config-manager --set-enabled powertools +sudo dnf install -y zlib-devel zlib-static xz-devel snappy-devel jansson jansson-devel pkgconfig libatomic libatomic-static libstdc++-static ``` ## 3.2 On macOS @@ -110,7 +123,7 @@ cd TDengine At the moment, TDengine server supports running on Linux/Windows/MacOS systems. Any application can also choose the RESTful interface provided by taosAdapter to connect the taosd service. TDengine supports X64/ARM64 CPU, and it will support MIPS64, Alpha64, ARM32, RISC-V and other CPU architectures in the future. Right now we don't support build with cross-compiling environment. -You can choose to install through source code, [container](https://docs.tdengine.com/get-started/docker/), [installation package](https://docs.tdengine.com/get-started/package/) or [Kubernetes](https://docs.tdengine.com/deployment/k8s/). This quick guide only applies to installing from source. +You can choose to install through source code, [container](https://docs.tdengine.com/get-started/docker/), [installation package](https://docs.tdengine.com/get-started/package/) or [Kubernetes](https://docs.tdengine.com/deployment/k8s/). This quick guide only applies to install from source. TDengine provide a few useful tools such as taosBenchmark (was named taosdemo) and taosdump. They were part of TDengine. By default, TDengine compiling does not include taosTools. You can use `cmake .. -DBUILD_TOOLS=true` to make them be compiled with TDengine. @@ -140,7 +153,6 @@ make You can use Jemalloc as memory allocator instead of glibc: ```bash -apt install autoconf cmake .. -DJEMALLOC_ENABLED=true ``` @@ -271,18 +283,20 @@ option "-c test/cfg" specifies the system configuration file directory. ## 6.2 Run TDengine on Windows -To start the service after installation on Windows, in a terminal, use: +You can start TDengine server on windows platform with below commands: -```bash -to be updated +```cmd +.\build\bin\taosd.exe -c test\cfg ``` -Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use: +In another terminal, use the TDengine CLI to connect the server: -```bash -taos +```cmd +.\build\bin\taos.exe -c test\cfg ``` +option "-c test/cfg" specifies the system configuration file directory. + ## 6.3 Run TDengine on macOS To start the service after installation on macOS, double-click the /applications/TDengine to start the program, or in a terminal, use: diff --git a/tests/README.md b/tests/README.md index 55e6688a8f..bd5696fc83 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,5 +1,26 @@ # Testing TDengine +## Install the required tools + +Install Python3. + +```bash +apt install python3 +apt install python3-pip +``` + +Install the dependent Python components. + +```bash +pip3 install pandas psutil fabric2 requests faker simplejson toml pexpect tzlocal distro decorator loguru hyperloglog +``` + +Install the Python connector for TDengine. + +```bash +pip3 install taospy taos-ws-py +``` + ## Unit Test Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run From c7b436fb62e93d1ca3af09f0833e5543b9f047b9 Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Thu, 9 Jan 2025 18:18:03 +0800 Subject: [PATCH 11/56] test:alter coverage describe --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 953bb7c6b1..00306aaf2b 100644 --- a/README.md +++ b/README.md @@ -338,8 +338,11 @@ Latest TDengine test coverage report can be found on [coveralls.io](https://cove ```bash cd tests -./run_local_coverage.sh +bash setup-lcov.sh -v 1.16 && ./run_local_coverage.sh -b main -c task +# on main branch and run cases in longtimeruning_cases.task +# for more infomation about options please refer to ./run_local_coverage.sh -h ``` +Please note that the -b and -i options will recompile TDengine with the -DCOVER=true option, which may take a amount of time. # 11. Contributing From e9945c096940c6a51a445732f282e76dd9d4532e Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Fri, 10 Jan 2025 11:46:29 +0800 Subject: [PATCH 12/56] udpate testing section to add -e parameter for unit test and two packages for centos 8 building section by charles --- README.md | 5 +++-- tests/README.md | 2 +- tests/unit-test/test.sh | 4 ++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 00306aaf2b..8824365fc6 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ sudo apt-get install -y gcc cmake build-essential git libjansson-dev libsnappy-d sudo yum update yum install -y epel-release gcc gcc-c++ make cmake git perl dnf-plugins-core yum config-manager --set-enabled powertools -yum install -y zlib-static xz-devel snappy-devel jansson-devel pkgconfig +yum install -y zlib-static xz-devel snappy-devel jansson-devel pkgconfig libatomic-static libstdc++-static ``` ### For Fedora or Rocky Linux @@ -342,7 +342,8 @@ bash setup-lcov.sh -v 1.16 && ./run_local_coverage.sh -b main -c task # on main branch and run cases in longtimeruning_cases.task # for more infomation about options please refer to ./run_local_coverage.sh -h ``` -Please note that the -b and -i options will recompile TDengine with the -DCOVER=true option, which may take a amount of time. +> [!NOTE] +> Please note that the -b and -i options will recompile TDengine with the -DCOVER=true option, which may take a amount of time. # 11. Contributing diff --git a/tests/README.md b/tests/README.md index bd5696fc83..9d7f98b564 100644 --- a/tests/README.md +++ b/tests/README.md @@ -27,7 +27,7 @@ Unit test script is the smallest testable part and developed for some function, the script with below command: ```bash -cd tests/unit-test/ +cd tests/unit-test/ -e 0 bash test.sh ``` diff --git a/tests/unit-test/test.sh b/tests/unit-test/test.sh index 21461bc6a5..46fc0aedb3 100755 --- a/tests/unit-test/test.sh +++ b/tests/unit-test/test.sh @@ -7,10 +7,10 @@ function usage() { } ent=1 -while getopts "eh" opt; do +while getopts "e:h" opt; do case $opt in e) - ent=1 + ent="$OPTARG" ;; h) usage From 53b3ff8f6cc5fdede941ec5cfb88df43d9816516 Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Fri, 10 Jan 2025 13:38:12 +0800 Subject: [PATCH 13/56] update readme --- README.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 8824365fc6..33874cf05d 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,8 @@ For user manual, system design and architecture, please refer to [TDengine Docum ```bash sudo apt-get udpate -sudo apt-get install -y gcc cmake build-essential git libjansson-dev libsnappy-dev liblzma-dev zlib1g-dev pkg-config +sudo apt-get install -y gcc cmake build-essential git libjansson-dev \ + libsnappy-dev liblzma-dev zlib1g-dev pkg-config ``` ### For CentOS 8 @@ -92,7 +93,8 @@ To build the [taosTools](https://github.com/taosdata/taos-tools) on Fedora or Ro ```bash sudo dnf install -y dnf-plugins-core sudo dnf config-manager --set-enabled powertools -sudo dnf install -y zlib-devel zlib-static xz-devel snappy-devel jansson jansson-devel pkgconfig libatomic libatomic-static libstdc++-static +sudo dnf install -y zlib-devel zlib-static xz-devel snappy-devel jansson \ + jansson-devel pkgconfig libatomic libatomic-static libstdc++-static ``` ## 3.2 On macOS @@ -144,8 +146,7 @@ You can run the bash script `build.sh` to build both TDengine and taosTools incl It equals to execute following commands: ```bash -mkdir debug -cd debug +mkdir debug && cd debug cmake .. -DBUILD_TOOLS=true -DBUILD_CONTRIB=true make ``` @@ -156,10 +157,8 @@ You can use Jemalloc as memory allocator instead of glibc: cmake .. -DJEMALLOC_ENABLED=true ``` -TDengine build script can detect the host machine's architecture on X86-64, X86, arm64 platform. -You can also specify CPUTYPE option like aarch64 too if the detection result is not correct: - -aarch64: +TDengine build script can auto-detect the host machine's architecture on x86, x86-64, arm64 platform. +You can also specify architecture manually by CPUTYPE option: ```bash cmake .. -DCPUTYPE=aarch64 && cmake --build . @@ -223,15 +222,13 @@ nmake ## 5.1 Install on Linux -After building successfully, TDengine can be installed by +After building successfully, TDengine can be installed by: ```bash sudo make install ``` -Users can find more information about directories installed on the system in the [directory and files](https://docs.tdengine.com/reference/directory/) section. - -Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/deploy-from-package/) for it. +Installing from source code will also configure service management for TDengine. Users can also choose to [install from packages](https://docs.tdengine.com/get-started/deploy-from-package/) for it. ## 5.2 Install on macOS @@ -279,11 +276,11 @@ In another terminal, use the TDengine CLI to connect the server: ./build/bin/taos -c test/cfg ``` -option "-c test/cfg" specifies the system configuration file directory. +Option `-c test/cfg` specifies the system configuration file directory. ## 6.2 Run TDengine on Windows -You can start TDengine server on windows platform with below commands: +You can start TDengine server on Windows platform with below commands: ```cmd .\build\bin\taosd.exe -c test\cfg From 982790b93a5e0ae1949e2e75075926ac36fd29d0 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Tue, 14 Jan 2025 11:32:25 +0800 Subject: [PATCH 14/56] Update build step notice and commands by charles --- tests/README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/tests/README.md b/tests/README.md index 9d7f98b564..6ac47ff7e0 100644 --- a/tests/README.md +++ b/tests/README.md @@ -21,14 +21,23 @@ Install the Python connector for TDengine. pip3 install taospy taos-ws-py ``` +>[!NTOE] +>Please make sure building operation with option '-DBUILD_TEST=true' has been finished, execute the below commands if not: + +```bash +cd debug +cmake .. -DBUILD_TEST=true -DBUILD_CONTRIB=true +make && make install +``` + ## Unit Test Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run the script with below command: ```bash -cd tests/unit-test/ -e 0 -bash test.sh +cd tests/unit-test/ +bash test.sh -e 0 ``` ## System Test From b3b4623fab3b52e06009db1573dc1bd4d8f7e1d1 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Tue, 14 Jan 2025 11:36:11 +0800 Subject: [PATCH 15/56] fix spelling issue --- tests/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/README.md b/tests/README.md index 6ac47ff7e0..35acb3f019 100644 --- a/tests/README.md +++ b/tests/README.md @@ -21,8 +21,8 @@ Install the Python connector for TDengine. pip3 install taospy taos-ws-py ``` ->[!NTOE] ->Please make sure building operation with option '-DBUILD_TEST=true' has been finished, execute the below commands if not: +> [!NOTE] +> Please make sure building operation with option '-DBUILD_TEST=true' has been finished, execute the below commands if not: ```bash cd debug From a1a6312db71f17b63300661cda0e5cad40bbc59d Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Tue, 14 Jan 2025 16:01:26 +0800 Subject: [PATCH 16/56] udpate test README to add build options by charles --- tests/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/README.md b/tests/README.md index 35acb3f019..2a25740dc3 100644 --- a/tests/README.md +++ b/tests/README.md @@ -22,11 +22,11 @@ pip3 install taospy taos-ws-py ``` > [!NOTE] -> Please make sure building operation with option '-DBUILD_TEST=true' has been finished, execute the below commands if not: +> Please make sure building operation with option '-DBUILD_TOOLS=true -DBUILD_TEST=true -DBUILD_CONTRIB=true' has been finished, execute the below commands if not: ```bash cd debug -cmake .. -DBUILD_TEST=true -DBUILD_CONTRIB=true +cmake .. -DBUILD_TOOLS=true -DBUILD_TEST=true -DBUILD_CONTRIB=true make && make install ``` From bb8ef7272573644681df3bd7e5aa32ec889dae1a Mon Sep 17 00:00:00 2001 From: haoranchen Date: Tue, 14 Jan 2025 16:46:39 +0800 Subject: [PATCH 17/56] Update test_smoking_selfhost.sh --- packaging/smokeTest/test_smoking_selfhost.sh | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packaging/smokeTest/test_smoking_selfhost.sh b/packaging/smokeTest/test_smoking_selfhost.sh index a25c5a6d90..6ed0b9c715 100755 --- a/packaging/smokeTest/test_smoking_selfhost.sh +++ b/packaging/smokeTest/test_smoking_selfhost.sh @@ -6,12 +6,6 @@ SUCCESS_FILE="success.txt" FAILED_FILE="failed.txt" REPORT_FILE="report.txt" -# Initialize/clear result files -> "$SUCCESS_FILE" -> "$FAILED_FILE" -> "$LOG_FILE" -> "$REPORT_FILE" - # Switch to the target directory TARGET_DIR="../../tests/system-test/" @@ -24,6 +18,12 @@ else exit 1 fi +# Initialize/clear result files +> "$SUCCESS_FILE" +> "$FAILED_FILE" +> "$LOG_FILE" +> "$REPORT_FILE" + # Define the Python commands to execute commands=( "python3 ./test.py -f 2-query/join.py" @@ -102,4 +102,4 @@ fi echo "Detailed logs can be found in: $(realpath "$LOG_FILE")" echo "Successful commands can be found in: $(realpath "$SUCCESS_FILE")" echo "Failed commands can be found in: $(realpath "$FAILED_FILE")" -echo "Test report can be found in: $(realpath "$REPORT_FILE")" \ No newline at end of file +echo "Test report can be found in: $(realpath "$REPORT_FILE")" From ad50cde25e637342d1a07b6e88a6e6f8859d7bea Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Tue, 14 Jan 2025 17:31:42 +0800 Subject: [PATCH 18/56] add TSBS and TestNG test description and fold up for installation, running section by charles --- README.md | 81 +++++++++++++++++++++++++++++++++++++------------ tests/README.md | 12 +++++++- 2 files changed, 72 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 33874cf05d..a39ddc0f78 100644 --- a/README.md +++ b/README.md @@ -30,13 +30,14 @@ English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine 1. [Documentation](#2-documentation) 1. [Prerequisites](#3-prerequisites) 1. [Building](#4-building) -1. [Installation](#5-installation) -1. [Running](#6-running) -1. [Testing](#7-testing) -1. [Releasing](#8-releasing) -1. [CI/CD](#9-cicd) -1. [Coverage](#10-coverage) -1. [Contributing](#11-contributing) +1. [Packaging](#5-packaging) +1. [Installation](#6-installation) +1. [Running](#7-running) +1. [Testing](#8-testing) +1. [Releasing](#9-releasing) +1. [CI/CD](#10-cicd) +1. [Coverage](#11-coverage) +1. [Contributing](#12-contributing) # 1. Introduction @@ -218,9 +219,17 @@ nmake ``` -# 5. Installation +# 5. Packaging -## 5.1 Install on Linux +TDengine packaging scripts depends on some private repositries currently, you can refer the link for detail steps. [Packaging](https://github.com/taosdata/TDinternal/tree/main?tab=readme-ov-file#5-packaging) + +# 6. Installation + +## 6.1 Install on Linux + +
+ +Detailed steps to install on Linux After building successfully, TDengine can be installed by: @@ -230,7 +239,13 @@ sudo make install Installing from source code will also configure service management for TDengine. Users can also choose to [install from packages](https://docs.tdengine.com/get-started/deploy-from-package/) for it. -## 5.2 Install on macOS +
+ +## 6.2 Install on macOS + +
+ +Detailed steps to install on macOS After building successfully, TDengine can be installed by: @@ -238,7 +253,13 @@ After building successfully, TDengine can be installed by: sudo make install ``` -## 5.3 Install on Windows +
+ +## 6.3 Install on Windows + +
+ +Detailed steps to install on windows After building successfully, TDengine can be installed by: @@ -246,9 +267,15 @@ After building successfully, TDengine can be installed by: nmake install ``` -# 6. Running +
-## 6.1 Run TDengine on Linux +# 7. Running + +## 7.1 Run TDengine on Linux + +
+ +Detailed steps to run on Linux To start the service after installation on linux, in a terminal, use: @@ -278,7 +305,13 @@ In another terminal, use the TDengine CLI to connect the server: Option `-c test/cfg` specifies the system configuration file directory. -## 6.2 Run TDengine on Windows +
+ +## 7.2 Run TDengine on Windows + +
+ +Detailed steps to run on windows You can start TDengine server on Windows platform with below commands: @@ -294,7 +327,13 @@ In another terminal, use the TDengine CLI to connect the server: option "-c test/cfg" specifies the system configuration file directory. -## 6.3 Run TDengine on macOS +
+ +## 7.3 Run TDengine on macOS + +
+ +Detailed steps to run on macOS To start the service after installation on macOS, double-click the /applications/TDengine to start the program, or in a terminal, use: @@ -310,15 +349,17 @@ taos If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown. -# 7. Testing +
+ +# 8. Testing For how to run different types of tests on TDengine, please see [Testing TDengine](./tests/README.md). -# 8. Releasing +# 9. Releasing For the complete list of TDengine Releases, please see [Releases](https://github.com/taosdata/TDengine/releases). -# 9. CI/CD +# 10. CI/CD Now, Jenkins is mainly used to build CI/CD pipeline for TDengine. To run the tests in the CI/CD pipeline, please run following commands: @@ -329,7 +370,7 @@ cd tests TDengine build check workflow can be found in this [Github Action](https://github.com/taosdata/TDengine/actions/workflows/taosd-ci-build.yml). -# 10. Coverage +# 11. Coverage Latest TDengine test coverage report can be found on [coveralls.io](https://coveralls.io/github/taosdata/TDengine). To create the test coverage report (in HTML format) locally, please run following commands: @@ -342,6 +383,6 @@ bash setup-lcov.sh -v 1.16 && ./run_local_coverage.sh -b main -c task > [!NOTE] > Please note that the -b and -i options will recompile TDengine with the -DCOVER=true option, which may take a amount of time. -# 11. Contributing +# 12. Contributing Please follow the [contribution guidelines](CONTRIBUTING.md) to contribute to TDengine. diff --git a/tests/README.md b/tests/README.md index 2a25740dc3..843b9379da 100644 --- a/tests/README.md +++ b/tests/README.md @@ -43,7 +43,7 @@ bash test.sh -e 0 ## System Test Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only -work for TDengine enterprise version, you can run the script with below command: +work for TDengine Enterprise Edition, you can run the script with below command: ```bash cd tests/system-test @@ -69,5 +69,15 @@ cd tests/script ./test.sh -f tsim/db/basic1.sim ``` +## TSBS Test +Time Series Benchmark Suite (TSBS) is an open-source performance benchmarking platform specifically designed for time-series data processing systems, such as databases. It provides a standardized approach to evaluating the performance of various databases by simulating typical use cases such as IoT and DevOps. +TSBS Test is based on the TDengine Enterprise Edition and need private repositry privilege, you can refer the link for detail steps. [TSBS Test](https://github.com/taosdata/TDinternal/tree/main?tab=readme-ov-file#85-tsbs-test) + +## TestNG Test + +TestNG Test is another test framwork which developed by python, functionally speaking, it's a supplement for system test, and +also run longer time than system test for stability testing purposes. + +TestNG Test is based on the TDengine Enterprise Edition and need private repositry privilege, you can refer the link for detail steps. [TestNG Test](https://github.com/taosdata/TDinternal/tree/main?tab=readme-ov-file#87-testng-test) From c947101b8f09263868450a5fbd58b200eaeb042a Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Tue, 14 Jan 2025 17:55:17 +0800 Subject: [PATCH 19/56] test:add how to add test cases --- tests/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/README.md b/tests/README.md index 843b9379da..83e77ac20b 100644 --- a/tests/README.md +++ b/tests/README.md @@ -69,6 +69,10 @@ cd tests/script ./test.sh -f tsim/db/basic1.sim ``` +## How TO Add Test Cases + +You can add sim test case under tests/script, python test case under tests/system-test or tests/army. When the case passes in the test branch, add the case to the cases.task file under tests/parallel_test, and then merge the pr into main branch to run in the future CI. + ## TSBS Test Time Series Benchmark Suite (TSBS) is an open-source performance benchmarking platform specifically designed for time-series data processing systems, such as databases. It provides a standardized approach to evaluating the performance of various databases by simulating typical use cases such as IoT and DevOps. From d9cbe335a7d96f525ede6caef736500004f2885a Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Tue, 14 Jan 2025 17:56:58 +0800 Subject: [PATCH 20/56] test:add how to add test cases --- tests/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/README.md b/tests/README.md index 83e77ac20b..d269a43f90 100644 --- a/tests/README.md +++ b/tests/README.md @@ -47,7 +47,7 @@ work for TDengine Enterprise Edition, you can run the script with below command: ```bash cd tests/system-test -python3 ./test.py -f 2-query/floor.py +python3 ./test.py -f 2-query/avg.py ``` ## Smoke Test From d15189291b1bbf927f4f2abbfdca1f4405c2caa6 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Thu, 16 Jan 2025 09:57:29 +0800 Subject: [PATCH 21/56] update testing README --- tests/README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/tests/README.md b/tests/README.md index d269a43f90..b47129e872 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,6 +1,13 @@ -# Testing TDengine +# Table of Contents +1. [Introduction](#1-introduction) +1. [Prerequisites](#2-prerequisites) +2. [Testing Guide](#3-testing-guide) -## Install the required tools +# 1. Introduction + +This manual is intended to provide users with comprehensive guidance to help them verify the TDengine function efficiently. The document is divided into three main sections: introduction, prerequisites and testing guide. + +# 2. Prerequisites Install Python3. @@ -30,6 +37,8 @@ cmake .. -DBUILD_TOOLS=true -DBUILD_TEST=true -DBUILD_CONTRIB=true make && make install ``` +# 3. Testing Guide + ## Unit Test Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run @@ -47,7 +56,7 @@ work for TDengine Enterprise Edition, you can run the script with below command: ```bash cd tests/system-test -python3 ./test.py -f 2-query/avg.py +python3 ./test.py -f 2-query/floor.py ``` ## Smoke Test @@ -68,7 +77,6 @@ In the early stage of TDengine development, test cases are run by an internal te cd tests/script ./test.sh -f tsim/db/basic1.sim ``` - ## How TO Add Test Cases You can add sim test case under tests/script, python test case under tests/system-test or tests/army. When the case passes in the test branch, add the case to the cases.task file under tests/parallel_test, and then merge the pr into main branch to run in the future CI. From 5c052c1325e908c7e7bd4d2981206d59cb33f42f Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Thu, 16 Jan 2025 11:55:57 +0800 Subject: [PATCH 22/56] docs: update the structure for testing readme --- tests/README.md | 102 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 72 insertions(+), 30 deletions(-) diff --git a/tests/README.md b/tests/README.md index b47129e872..07d576ab4c 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,35 +1,44 @@ # Table of Contents + 1. [Introduction](#1-introduction) 1. [Prerequisites](#2-prerequisites) -2. [Testing Guide](#3-testing-guide) +1. [Testing Guide](#3-testing-guide) + 1. [Unit Test](#31-unit-test) + 1. [System Test](#32-system-test) + 1. [Smoke Test](#33-smoke-test) + 1. [Legacy Test](#34-legacy-test) + 1. [Chaos Test](#35-chaos-test) + 1. [TSBS Test](#36-tsbs-test) # 1. Introduction -This manual is intended to provide users with comprehensive guidance to help them verify the TDengine function efficiently. The document is divided into three main sections: introduction, prerequisites and testing guide. +This manual is intended to provide users with comprehensive guidance to help them verify the TDengine function efficiently. The document is divided into three main sections: introduction, prerequisites and testing guide. -# 2. Prerequisites +# 2. Prerequisites -Install Python3. +- Install Python3 ```bash apt install python3 apt install python3-pip ``` -Install the dependent Python components. +- Install Python dependencies ```bash -pip3 install pandas psutil fabric2 requests faker simplejson toml pexpect tzlocal distro decorator loguru hyperloglog +pip3 install pandas psutil fabric2 requests faker simplejson \ + toml pexpect tzlocal distro decorator loguru hyperloglog ``` -Install the Python connector for TDengine. +- Install Python connector for TDengine ```bash pip3 install taospy taos-ws-py ``` -> [!NOTE] -> Please make sure building operation with option '-DBUILD_TOOLS=true -DBUILD_TEST=true -DBUILD_CONTRIB=true' has been finished, execute the below commands if not: +- Building + +Please make sure building operation with option `-DBUILD_TOOLS=true -DBUILD_TEST=true -DBUILD_CONTRIB=true` has been finished, otherwise execute commands below: ```bash cd debug @@ -39,57 +48,90 @@ make && make install # 3. Testing Guide -## Unit Test +In `tests` directory, there are different types of tests for TDengine. Below is a brief introduction about how to run them and how to add new cases. -Unit test script is the smallest testable part and developed for some function, method or class of TDengine, you can run -the script with below command: +## 3.1. Unit Test + +Unit test script is the smallest testable part and developed for some function, method or class of TDengine. + +### How to run tests? ```bash cd tests/unit-test/ bash test.sh -e 0 ``` -## System Test +### How to add new cases? + +Copy from the old version, need updates: +You can add sim test case under tests/script, python test case under tests/system-test or tests/army. When the case passes in the test branch, add the case to the cases.task file under tests/parallel_test, and then merge the pr into main branch to run in the future CI. + +## 3.2. System Test Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only -work for TDengine Enterprise Edition, you can run the script with below command: +work for TDengine Enterprise Edition. + +### How to run tests? ```bash cd tests/system-test python3 ./test.py -f 2-query/floor.py ``` -## Smoke Test +### How to add new cases? -Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine, you can run the -script with commands below: +[Placeholder] + +## 3.3. Smoke Test + +Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine. + +### How to run tests? ```bash cd /root/TDengine/packaging/smokeTest ./test_smoking_selfhost.sh ``` -## Legacy Test +### How to add new cases? -In the early stage of TDengine development, test cases are run by an internal test framework called TSIM, which is developed in C++. To run the legacy test cases, please execute the following commands: +[Placeholder] + +## 3.4. Legacy Test + +In the early stage of TDengine development, test cases are run by an internal test framework called TSIM, which is developed in C++. + +### How to run tests? + +To run the legacy test cases, please execute the following commands: ```bash cd tests/script ./test.sh -f tsim/db/basic1.sim ``` -## How TO Add Test Cases -You can add sim test case under tests/script, python test case under tests/system-test or tests/army. When the case passes in the test branch, add the case to the cases.task file under tests/parallel_test, and then merge the pr into main branch to run in the future CI. +### How to add new cases? -## TSBS Test +[Placeholder] -Time Series Benchmark Suite (TSBS) is an open-source performance benchmarking platform specifically designed for time-series data processing systems, such as databases. It provides a standardized approach to evaluating the performance of various databases by simulating typical use cases such as IoT and DevOps. +## 3.5. Chaos Test + +[Desciprtion] + +### How to run tests? + +[Placeholder] + +### How to add new cases? + +[Placeholder] + +## 3.6. TSBS Test + +[Time Series Benchmark Suite (TSBS)](https://github.com/timescale/tsbs) is an open-source performance benchmarking platform specifically designed for time-series data processing systems, such as databases. It provides a standardized approach to evaluating the performance of various databases by simulating typical use cases such as IoT and DevOps. + +### How to run tests? + +Need updates: must be run from public repo! TSBS Test is based on the TDengine Enterprise Edition and need private repositry privilege, you can refer the link for detail steps. [TSBS Test](https://github.com/taosdata/TDinternal/tree/main?tab=readme-ov-file#85-tsbs-test) - -## TestNG Test - -TestNG Test is another test framwork which developed by python, functionally speaking, it's a supplement for system test, and -also run longer time than system test for stability testing purposes. - -TestNG Test is based on the TDengine Enterprise Edition and need private repositry privilege, you can refer the link for detail steps. [TestNG Test](https://github.com/taosdata/TDinternal/tree/main?tab=readme-ov-file#87-testng-test) From 674a3818be425829a57cdaef6f03a11a7e59ee5d Mon Sep 17 00:00:00 2001 From: haoranchen Date: Thu, 16 Jan 2025 12:07:43 +0800 Subject: [PATCH 23/56] Update README.md --- tests/README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/tests/README.md b/tests/README.md index 07d576ab4c..318024e8ff 100644 --- a/tests/README.md +++ b/tests/README.md @@ -130,6 +130,31 @@ cd tests/script [Time Series Benchmark Suite (TSBS)](https://github.com/timescale/tsbs) is an open-source performance benchmarking platform specifically designed for time-series data processing systems, such as databases. It provides a standardized approach to evaluating the performance of various databases by simulating typical use cases such as IoT and DevOps. +1. Clone the code and run the tests locally on your machine. Ensure that your virtual machine supports the AVX instruction set: +```bash + cd /usr/local/src && git clone https://github.com/taosdata/tsbs-internal.git tsbs && \ + cd tsbs && git checkout enh/chr-td-33357 && \ + cd scripts/tsdbComp && ./testTsbs.sh +``` +2. When testing the client and server on separate machines, you should set up your environment as outlined in the steps below: + + 2.1. Modify IP and host of client and server in `test.ini` + ```ini + clientIP="192.168.0.203" # client ip + clientHost="trd03" # client hostname + serverIP="192.168.0.204" # server ip + serverHost="trd04" # server hostname + ``` + 2.2. Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: + ```ini + serverPass="taosdata123" # server root password + ``` + 2.3. Run the following command to start the test: + ```bash + ./testTsbs.sh + ``` +3. When the test is done, the result can be found in `/data2/` directory, which can also be configured in `test.ini`. + ### How to run tests? Need updates: must be run from public repo! From 78479871339b39e3e3f89c63c9bd1a222c4db1e1 Mon Sep 17 00:00:00 2001 From: haoranchen Date: Thu, 16 Jan 2025 12:09:18 +0800 Subject: [PATCH 24/56] add tsbs for README.md --- tests/README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/tests/README.md b/tests/README.md index 318024e8ff..0e870b1fea 100644 --- a/tests/README.md +++ b/tests/README.md @@ -130,6 +130,8 @@ cd tests/script [Time Series Benchmark Suite (TSBS)](https://github.com/timescale/tsbs) is an open-source performance benchmarking platform specifically designed for time-series data processing systems, such as databases. It provides a standardized approach to evaluating the performance of various databases by simulating typical use cases such as IoT and DevOps. +### How to run tests? + 1. Clone the code and run the tests locally on your machine. Ensure that your virtual machine supports the AVX instruction set: ```bash cd /usr/local/src && git clone https://github.com/taosdata/tsbs-internal.git tsbs && \ @@ -154,9 +156,3 @@ cd tests/script ./testTsbs.sh ``` 3. When the test is done, the result can be found in `/data2/` directory, which can also be configured in `test.ini`. - -### How to run tests? - -Need updates: must be run from public repo! - -TSBS Test is based on the TDengine Enterprise Edition and need private repositry privilege, you can refer the link for detail steps. [TSBS Test](https://github.com/taosdata/TDinternal/tree/main?tab=readme-ov-file#85-tsbs-test) From d4aec7a3d2b0ffa7a5c609ee857db9e76b7a37e1 Mon Sep 17 00:00:00 2001 From: haoranchen Date: Thu, 16 Jan 2025 12:22:03 +0800 Subject: [PATCH 25/56] docs: add note for tsbs test --- tests/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/README.md b/tests/README.md index 0e870b1fea..1466285096 100644 --- a/tests/README.md +++ b/tests/README.md @@ -138,6 +138,10 @@ cd tests/script cd tsbs && git checkout enh/chr-td-33357 && \ cd scripts/tsdbComp && ./testTsbs.sh ``` +> [!NOTE] +> If you want to quickly verify the test environment, please set the `caseType` in `test.ini` file to `cputest`. The current default test is the CPU scenario. After running, the test will take a very long time. + + 2. When testing the client and server on separate machines, you should set up your environment as outlined in the steps below: 2.1. Modify IP and host of client and server in `test.ini` From 28af1cc214b8108b045b3c992774ff7590be8a51 Mon Sep 17 00:00:00 2001 From: haoranchen Date: Thu, 16 Jan 2025 12:29:34 +0800 Subject: [PATCH 26/56] Update README.md --- tests/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/README.md b/tests/README.md index 1466285096..da70c9078d 100644 --- a/tests/README.md +++ b/tests/README.md @@ -139,7 +139,9 @@ cd tests/script cd scripts/tsdbComp && ./testTsbs.sh ``` > [!NOTE] -> If you want to quickly verify the test environment, please set the `caseType` in `test.ini` file to `cputest`. The current default test is the CPU scenario. After running, the test will take a very long time. +> The default case type, CPU test, takes a long time to run. +> +> If you want to run quick test to verify the test environment, please set `caseType=cputest` in test.ini . 2. When testing the client and server on separate machines, you should set up your environment as outlined in the steps below: From 64c6562be3c38d901ec443f5927aff3470db4c00 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Thu, 16 Jan 2025 15:02:32 +0800 Subject: [PATCH 27/56] update README to adjust the structure --- README.md | 127 +++++++++++++++++++++++++++--------------------- tests/README.md | 41 +++++----------- 2 files changed, 84 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index a39ddc0f78..495c28c2c3 100644 --- a/README.md +++ b/README.md @@ -29,15 +29,28 @@ English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine 1. [Introduction](#1-introduction) 1. [Documentation](#2-documentation) 1. [Prerequisites](#3-prerequisites) -1. [Building](#4-building) -1. [Packaging](#5-packaging) -1. [Installation](#6-installation) -1. [Running](#7-running) -1. [Testing](#8-testing) -1. [Releasing](#9-releasing) -1. [CI/CD](#10-cicd) -1. [Coverage](#11-coverage) -1. [Contributing](#12-contributing) + - [3.1 Prerequisites On Linux](#31-on-linux) + - [3.2 Prerequisites On macOS](#32-on-macos) + - [3.3 Prerequisites On Windows](#33-on-windows) + - [3.4 Clone the repo](#34-clone-the-repo) +2. [Building](#4-building) + - [4.1 Build on Linux](#41-build-on-linux) + - [4.2 Build on macOS](#42-build-on-macos) + - [4.3 Build On Windows](#43-build-on-windows) +3. [Packaging](#5-packaging) +4. [Installation](#6-installation) + - [6.1 Install on Linux](#61-install-on-linux) + - [6.2 Install on macOS](#62-install-on-macos) + - [6.3 Install on Windows](#63-install-on-windows) +5. [Running](#7-running) + - [7.1 Run TDengine on Linux](#71-run-tdengine-on-linux) + - [7.2 Run TDengine on macOS](#72-run-tdengine-on-macos) + - [7.3 Run TDengine on Windows](#73-run-tdengine-on-windows) +6. [Testing](#8-testing) +7. [Releasing](#9-releasing) +8. [CI/CD](#10-cicd) +9. [Coverage](#11-coverage) +10. [Contributing](#12-contributing) # 1. Introduction @@ -65,7 +78,11 @@ For user manual, system design and architecture, please refer to [TDengine Docum ## 3.1 On Linux -### For Ubuntu 18.04 or Later +
+ +Install required tools on Linux + +### For Ubuntu 18.04、20.04、22.04 ```bash sudo apt-get udpate @@ -82,36 +99,38 @@ yum config-manager --set-enabled powertools yum install -y zlib-static xz-devel snappy-devel jansson-devel pkgconfig libatomic-static libstdc++-static ``` -### For Fedora or Rocky Linux - -```bash -sudo dnf install -y gcc gcc-c++ make cmake git perl -sudo dnf install -y zlib-devel xz-devel snappy-devel jansson-devel pkgconfig -``` - -To build the [taosTools](https://github.com/taosdata/taos-tools) on Fedora or Rocky, the following packages need to be installed. - -```bash -sudo dnf install -y dnf-plugins-core -sudo dnf config-manager --set-enabled powertools -sudo dnf install -y zlib-devel zlib-static xz-devel snappy-devel jansson \ - jansson-devel pkgconfig libatomic libatomic-static libstdc++-static -``` +
## 3.2 On macOS +
+ +Install required tools on macOS + Please intall the dependencies with [brew](https://brew.sh/). ```bash brew install argp-standalone gflags pkgconfig ``` +
+ ## 3.3 On Windows +
+ +Install required tools on Windows + Work in Progress. +
+ ## 3.4 Clone the repo +
+ +Clone the repo + Clone the repository to the target machine: ```bash @@ -122,6 +141,8 @@ cd TDengine > [!NOTE] > TDengine Connectors can be found in following repositories: [JDBC Connector](https://github.com/taosdata/taos-connector-jdbc), [Go Connector](https://github.com/taosdata/driver-go), [Python Connector](https://github.com/taosdata/taos-connector-python), [Node.js Connector](https://github.com/taosdata/taos-connector-node), [C# Connector](https://github.com/taosdata/taos-connector-dotnet), [Rust Connector](https://github.com/taosdata/taos-connector-rust). +
+ # 4. Building At the moment, TDengine server supports running on Linux/Windows/MacOS systems. Any application can also choose the RESTful interface provided by taosAdapter to connect the taosd service. TDengine supports X64/ARM64 CPU, and it will support MIPS64, Alpha64, ARM32, RISC-V and other CPU architectures in the future. Right now we don't support build with cross-compiling environment. @@ -307,29 +328,7 @@ Option `-c test/cfg` specifies the system configuration file directory. -## 7.2 Run TDengine on Windows - -
- -Detailed steps to run on windows - -You can start TDengine server on Windows platform with below commands: - -```cmd -.\build\bin\taosd.exe -c test\cfg -``` - -In another terminal, use the TDengine CLI to connect the server: - -```cmd -.\build\bin\taos.exe -c test\cfg -``` - -option "-c test/cfg" specifies the system configuration file directory. - -
- -## 7.3 Run TDengine on macOS +## 7.2 Run TDengine on macOS
@@ -351,6 +350,29 @@ If TDengine CLI connects the server successfully, welcome messages and version i
+ +## 7.3 Run TDengine on Windows + +
+ +Detailed steps to run on windows + +You can start TDengine server on Windows platform with below commands: + +```cmd +.\build\bin\taosd.exe -c test\cfg +``` + +In another terminal, use the TDengine CLI to connect the server: + +```cmd +.\build\bin\taos.exe -c test\cfg +``` + +option "-c test/cfg" specifies the system configuration file directory. + +
+ # 8. Testing For how to run different types of tests on TDengine, please see [Testing TDengine](./tests/README.md). @@ -359,14 +381,9 @@ For how to run different types of tests on TDengine, please see [Testing TDengin For the complete list of TDengine Releases, please see [Releases](https://github.com/taosdata/TDengine/releases). -# 10. CI/CD +# 10. Workflow -Now, Jenkins is mainly used to build CI/CD pipeline for TDengine. To run the tests in the CI/CD pipeline, please run following commands: - -```bash -cd tests -./run_all_ci_cases.sh -b main # on main branch -``` +Now, Jenkins is mainly used to build CI/CD pipeline for TDengine. TDengine build check workflow can be found in this [Github Action](https://github.com/taosdata/TDengine/actions/workflows/taosd-ci-build.yml). diff --git a/tests/README.md b/tests/README.md index da70c9078d..3333ae2489 100644 --- a/tests/README.md +++ b/tests/README.md @@ -8,12 +8,15 @@ 1. [Smoke Test](#33-smoke-test) 1. [Legacy Test](#34-legacy-test) 1. [Chaos Test](#35-chaos-test) - 1. [TSBS Test](#36-tsbs-test) + 1. [CI Test](#36-ci-test) # 1. Introduction This manual is intended to provide users with comprehensive guidance to help them verify the TDengine function efficiently. The document is divided into three main sections: introduction, prerequisites and testing guide. +> [!NOTICE] +> The below commands and test scripts are verified on linux (Ubuntu 18.04、20.04、22.04) locally. + # 2. Prerequisites - Install Python3 @@ -126,39 +129,19 @@ cd tests/script [Placeholder] -## 3.6. TSBS Test +## 3.6 CI Test -[Time Series Benchmark Suite (TSBS)](https://github.com/timescale/tsbs) is an open-source performance benchmarking platform specifically designed for time-series data processing systems, such as databases. It provides a standardized approach to evaluating the performance of various databases by simulating typical use cases such as IoT and DevOps. +[Desciprtion] ### How to run tests? -1. Clone the code and run the tests locally on your machine. Ensure that your virtual machine supports the AVX instruction set: +To run the CI tests, please run following commands: + ```bash - cd /usr/local/src && git clone https://github.com/taosdata/tsbs-internal.git tsbs && \ - cd tsbs && git checkout enh/chr-td-33357 && \ - cd scripts/tsdbComp && ./testTsbs.sh +cd tests +./run_all_ci_cases.sh -b main # on main branch ``` -> [!NOTE] -> The default case type, CPU test, takes a long time to run. -> -> If you want to run quick test to verify the test environment, please set `caseType=cputest` in test.ini . +### How to add new cases? -2. When testing the client and server on separate machines, you should set up your environment as outlined in the steps below: - - 2.1. Modify IP and host of client and server in `test.ini` - ```ini - clientIP="192.168.0.203" # client ip - clientHost="trd03" # client hostname - serverIP="192.168.0.204" # server ip - serverHost="trd04" # server hostname - ``` - 2.2. Set up passwordless login between the client and server; otherwise, you'll need to configure the server password: - ```ini - serverPass="taosdata123" # server root password - ``` - 2.3. Run the following command to start the test: - ```bash - ./testTsbs.sh - ``` -3. When the test is done, the result can be found in `/data2/` directory, which can also be configured in `test.ini`. +[Placeholder] From c7337fe4a34d5ac1d7237b0e47162562bfe35fe2 Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Thu, 16 Jan 2025 15:10:47 +0800 Subject: [PATCH 28/56] test:add test type --- tests/run_all_ci_cases.sh | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/tests/run_all_ci_cases.sh b/tests/run_all_ci_cases.sh index 41040f3c43..43127f75e2 100755 --- a/tests/run_all_ci_cases.sh +++ b/tests/run_all_ci_cases.sh @@ -23,16 +23,20 @@ function printHelp() { echo " -b [Build test branch] Build test branch (default: null)" echo " Options: " echo " e.g., -b main (pull main branch, build and install)" + echo " -t [Run test cases] Run test cases type(default: all)" + echo " Options: " + echo " e.g., -t all/python/legacy" echo " -s [Save cases log] Save cases log(default: notsave)" echo " Options:" - echo " e.g., -c notsave : do not save the log " - echo " -c save : default save ci case log in Project dir/tests/ci_bak" + echo " e.g., -s notsave : do not save the log " + echo " -s save : default save ci case log in Project dir/tests/ci_bak" exit 0 } # Initialization parameter PROJECT_DIR="" BRANCH="" +TEST_TYPE="all" SAVE_LOG="notsave" # Parse command line parameters @@ -44,6 +48,9 @@ while getopts "hb:d:s:" arg; do b) BRANCH=$OPTARG ;; + t) + TEST_TYPE=$OPTARG + ;; s) SAVE_LOG=$OPTARG ;; @@ -315,9 +322,9 @@ function runTest() { [ -d sim ] && rm -rf sim [ -f $TDENGINE_ALLCI_REPORT ] && rm $TDENGINE_ALLCI_REPORT - runUnitTest runSimCases runPythonCases + runUnitTest stopTaosd cd $TDENGINE_DIR/tests/script @@ -361,7 +368,13 @@ print_color "$GREEN" "Run all ci test cases" | tee -a $WORK_DIR/date.log stopTaosd -runTest +if [ -z "$TEST_TYPE" ]; then + runTest +elif [ "$TEST_TYPE" = "python" -o "$TEST_TYPE" = "PYTHON"]; then + runPythonCases +elif [ "$TEST_TYPE" = "legacy" -o "$TEST_TYPE" = "LEGACY"]; then + runSimCases +fi date >> $WORK_DIR/date.log print_color "$GREEN" "End of ci test cases" | tee -a $WORK_DIR/date.log \ No newline at end of file From 130e8a3e068d3037d3f38b885e898e1584556a14 Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Thu, 16 Jan 2025 15:14:29 +0800 Subject: [PATCH 29/56] test:add test type --- tests/run_all_ci_cases.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/run_all_ci_cases.sh b/tests/run_all_ci_cases.sh index 43127f75e2..1edc279e57 100755 --- a/tests/run_all_ci_cases.sh +++ b/tests/run_all_ci_cases.sh @@ -40,7 +40,7 @@ TEST_TYPE="all" SAVE_LOG="notsave" # Parse command line parameters -while getopts "hb:d:s:" arg; do +while getopts "hb:d:t:s:" arg; do case $arg in d) PROJECT_DIR=$OPTARG From a5d327df412987b5f56f724b0da229d1f451e279 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Thu, 16 Jan 2025 15:17:03 +0800 Subject: [PATCH 30/56] remove CICD cotents of TDengine README and update testing sructure of testing guide --- README.md | 2 -- tests/README.md | 96 +++++++++++++++++++++++++------------------------ 2 files changed, 50 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 495c28c2c3..baf6097c30 100644 --- a/README.md +++ b/README.md @@ -383,8 +383,6 @@ For the complete list of TDengine Releases, please see [Releases](https://github # 10. Workflow -Now, Jenkins is mainly used to build CI/CD pipeline for TDengine. - TDengine build check workflow can be found in this [Github Action](https://github.com/taosdata/TDengine/actions/workflows/taosd-ci-build.yml). # 11. Coverage diff --git a/tests/README.md b/tests/README.md index 3333ae2489..dcec10eb7a 100644 --- a/tests/README.md +++ b/tests/README.md @@ -3,18 +3,19 @@ 1. [Introduction](#1-introduction) 1. [Prerequisites](#2-prerequisites) 1. [Testing Guide](#3-testing-guide) - 1. [Unit Test](#31-unit-test) - 1. [System Test](#32-system-test) - 1. [Smoke Test](#33-smoke-test) - 1. [Legacy Test](#34-legacy-test) - 1. [Chaos Test](#35-chaos-test) - 1. [CI Test](#36-ci-test) + - [3.1 CI Test](#31-ci-test) + - [3.1.1 Unit Test](#311-unit-test) + - [3.1.2 System Test](#312-system-test) + - [3.1.3 Legacy Test](#313-legacy-test) + - [3.2 Smoke Test](#32-smoke-test) + - [3.3 Chaos Test](#33-chaos-test) + # 1. Introduction This manual is intended to provide users with comprehensive guidance to help them verify the TDengine function efficiently. The document is divided into three main sections: introduction, prerequisites and testing guide. -> [!NOTICE] +> [!NOTE] > The below commands and test scripts are verified on linux (Ubuntu 18.04、20.04、22.04) locally. # 2. Prerequisites @@ -53,25 +54,44 @@ make && make install In `tests` directory, there are different types of tests for TDengine. Below is a brief introduction about how to run them and how to add new cases. -## 3.1. Unit Test + +## 3.1 CI Test + +[Desciprtion] + +### How to run tests? + +To run the CI tests, please run following commands: + +```bash +cd tests +./run_all_ci_cases.sh -b main # on main branch +``` + +### How to add new cases? + +[Placeholder] + + +### 3.1.1 Unit Test Unit test script is the smallest testable part and developed for some function, method or class of TDengine. -### How to run tests? +#### How to run tests? ```bash cd tests/unit-test/ bash test.sh -e 0 ``` -### How to add new cases? +#### How to add new cases? Copy from the old version, need updates: You can add sim test case under tests/script, python test case under tests/system-test or tests/army. When the case passes in the test branch, add the case to the cases.task file under tests/parallel_test, and then merge the pr into main branch to run in the future CI. -## 3.2. System Test +## 3.1.2 System Test -Python test script includes almost all of the functions of TDengine, so some test case maybe fail cause the function only +Python test script includes all of the functions of TDengine OSS, so some test case maybe fail cause the function only work for TDengine Enterprise Edition. ### How to run tests? @@ -85,22 +105,7 @@ python3 ./test.py -f 2-query/floor.py [Placeholder] -## 3.3. Smoke Test - -Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine. - -### How to run tests? - -```bash -cd /root/TDengine/packaging/smokeTest -./test_smoking_selfhost.sh -``` - -### How to add new cases? - -[Placeholder] - -## 3.4. Legacy Test +## 3.1.3 Legacy Test In the early stage of TDengine development, test cases are run by an internal test framework called TSIM, which is developed in C++. @@ -117,31 +122,30 @@ cd tests/script [Placeholder] -## 3.5. Chaos Test -[Desciprtion] +## 3.2 Smoke Test + +Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine. ### How to run tests? -[Placeholder] - -### How to add new cases? - -[Placeholder] - -## 3.6 CI Test - -[Desciprtion] - -### How to run tests? - -To run the CI tests, please run following commands: - ```bash -cd tests -./run_all_ci_cases.sh -b main # on main branch +cd /root/TDengine/packaging/smokeTest +./test_smoking_selfhost.sh ``` ### How to add new cases? [Placeholder] + +## 3.3 Chaos Test + +[Desciprtion] + +### How to run tests? + +[Placeholder] + +### How to add new cases? + +[Placeholder] From ac10ed5af5c317f4538516c74d14c9a53ee73819 Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Thu, 16 Jan 2025 15:25:06 +0800 Subject: [PATCH 31/56] test:add test type --- tests/run_all_ci_cases.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/run_all_ci_cases.sh b/tests/run_all_ci_cases.sh index 1edc279e57..b8e68b5907 100755 --- a/tests/run_all_ci_cases.sh +++ b/tests/run_all_ci_cases.sh @@ -370,9 +370,9 @@ stopTaosd if [ -z "$TEST_TYPE" ]; then runTest -elif [ "$TEST_TYPE" = "python" -o "$TEST_TYPE" = "PYTHON"]; then +elif [ "$TEST_TYPE" = "python" -o "$TEST_TYPE" = "PYTHON" ]; then runPythonCases -elif [ "$TEST_TYPE" = "legacy" -o "$TEST_TYPE" = "LEGACY"]; then +elif [ "$TEST_TYPE" = "legacy" -o "$TEST_TYPE" = "LEGACY" ]; then runSimCases fi From b2ac2d51c59e5bbbad8bbce040236231b4ced5de Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Thu, 16 Jan 2025 15:37:57 +0800 Subject: [PATCH 32/56] test:add test type --- tests/run_all_ci_cases.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/run_all_ci_cases.sh b/tests/run_all_ci_cases.sh index b8e68b5907..1374fc1431 100755 --- a/tests/run_all_ci_cases.sh +++ b/tests/run_all_ci_cases.sh @@ -36,7 +36,7 @@ function printHelp() { # Initialization parameter PROJECT_DIR="" BRANCH="" -TEST_TYPE="all" +TEST_TYPE="" SAVE_LOG="notsave" # Parse command line parameters @@ -368,7 +368,7 @@ print_color "$GREEN" "Run all ci test cases" | tee -a $WORK_DIR/date.log stopTaosd -if [ -z "$TEST_TYPE" ]; then +if [ -z "$TEST_TYPE" -o "$TEST_TYPE" = "all" -o "$TEST_TYPE" = "ALL" ]; then runTest elif [ "$TEST_TYPE" = "python" -o "$TEST_TYPE" = "PYTHON" ]; then runPythonCases From d92870e6818749c3df90f30cbd8c5331334ccaa7 Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Thu, 16 Jan 2025 16:01:17 +0800 Subject: [PATCH 33/56] test:add test type --- tests/README.md | 45 +++++++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/tests/README.md b/tests/README.md index dcec10eb7a..225bd2797d 100644 --- a/tests/README.md +++ b/tests/README.md @@ -61,7 +61,7 @@ In `tests` directory, there are different types of tests for TDengine. Below is ### How to run tests? -To run the CI tests, please run following commands: +If this is the first time to run all the CI tests, it is recommended to add the test branch, please run like following commands: ```bash cd tests @@ -70,14 +70,21 @@ cd tests ### How to add new cases? -[Placeholder] +[You can add sim test case under tests/script, python test case under tests/system-test or tests/army. When the case passes in the test branch, add the case to the cases.task file under tests/parallel_test, and then merge the pr into main branch to run in the future CI.] ### 3.1.1 Unit Test Unit test script is the smallest testable part and developed for some function, method or class of TDengine. -#### How to run tests? +### How to run single test case? + +```bash +cd debug/build/bin +./osTimeTests +``` + +### How to run all unit test cases? ```bash cd tests/unit-test/ @@ -87,21 +94,28 @@ bash test.sh -e 0 #### How to add new cases? Copy from the old version, need updates: -You can add sim test case under tests/script, python test case under tests/system-test or tests/army. When the case passes in the test branch, add the case to the cases.task file under tests/parallel_test, and then merge the pr into main branch to run in the future CI. + ## 3.1.2 System Test Python test script includes all of the functions of TDengine OSS, so some test case maybe fail cause the function only work for TDengine Enterprise Edition. -### How to run tests? +### How to run single test case? ```bash cd tests/system-test python3 ./test.py -f 2-query/floor.py ``` -### How to add new cases? +### How to run all system test cases? + +```bash +cd tests +./run_all_ci_cases.sh -t python # all python cases +``` + +### How to add new case? [Placeholder] @@ -109,7 +123,7 @@ python3 ./test.py -f 2-query/floor.py In the early stage of TDengine development, test cases are run by an internal test framework called TSIM, which is developed in C++. -### How to run tests? +### How to run single test case? To run the legacy test cases, please execute the following commands: @@ -118,7 +132,14 @@ cd tests/script ./test.sh -f tsim/db/basic1.sim ``` -### How to add new cases? +### How to run all legacy test cases? + +```bash +cd tests +./run_all_ci_cases.sh -t legacy # all legacy cases +``` + +### How to add new case? [Placeholder] @@ -127,14 +148,14 @@ cd tests/script Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine. -### How to run tests? +### How to run test? ```bash cd /root/TDengine/packaging/smokeTest ./test_smoking_selfhost.sh ``` -### How to add new cases? +### How to add new case? [Placeholder] @@ -142,10 +163,10 @@ cd /root/TDengine/packaging/smokeTest [Desciprtion] -### How to run tests? +### How to run test? [Placeholder] -### How to add new cases? +### How to add new case? [Placeholder] From 9cd1113c93d06ce22d7d00c718bb7ef1db60dc71 Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Thu, 16 Jan 2025 16:11:49 +0800 Subject: [PATCH 34/56] update TDengine README workflow link --- README.md | 18 +++++++++--------- tests/README.md | 2 ++ 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index baf6097c30..91232136c5 100644 --- a/README.md +++ b/README.md @@ -33,24 +33,24 @@ English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine - [3.2 Prerequisites On macOS](#32-on-macos) - [3.3 Prerequisites On Windows](#33-on-windows) - [3.4 Clone the repo](#34-clone-the-repo) -2. [Building](#4-building) +1. [Building](#4-building) - [4.1 Build on Linux](#41-build-on-linux) - [4.2 Build on macOS](#42-build-on-macos) - [4.3 Build On Windows](#43-build-on-windows) -3. [Packaging](#5-packaging) -4. [Installation](#6-installation) +1. [Packaging](#5-packaging) +1. [Installation](#6-installation) - [6.1 Install on Linux](#61-install-on-linux) - [6.2 Install on macOS](#62-install-on-macos) - [6.3 Install on Windows](#63-install-on-windows) -5. [Running](#7-running) +1. [Running](#7-running) - [7.1 Run TDengine on Linux](#71-run-tdengine-on-linux) - [7.2 Run TDengine on macOS](#72-run-tdengine-on-macos) - [7.3 Run TDengine on Windows](#73-run-tdengine-on-windows) -6. [Testing](#8-testing) -7. [Releasing](#9-releasing) -8. [CI/CD](#10-cicd) -9. [Coverage](#11-coverage) -10. [Contributing](#12-contributing) +1. [Testing](#8-testing) +1. [Releasing](#9-releasing) +1. [Workflow](#10-workflow) +1. [Coverage](#11-coverage) +1. [Contributing](#12-contributing) # 1. Introduction diff --git a/tests/README.md b/tests/README.md index 225bd2797d..e51a6a0e49 100644 --- a/tests/README.md +++ b/tests/README.md @@ -143,6 +143,8 @@ cd tests [Placeholder] +> [!NOTE] +> TSIM test framwork is replaced by system test currently, suggest to add new test scripts to system test. ## 3.2 Smoke Test From 008233ccf6e8efec22613ad84c31b496b1504c5a Mon Sep 17 00:00:00 2001 From: jiajingbin Date: Thu, 16 Jan 2025 16:22:17 +0800 Subject: [PATCH 35/56] doc: add Chaos Test to README and update some functions --- tests/README.md | 12 ++++++--- tests/pytest/auto_crash_gen.py | 15 ++++++----- tests/pytest/auto_crash_gen_valgrind.py | 14 +++++------ .../pytest/auto_crash_gen_valgrind_cluster.py | 18 ++++++------- tests/system-test/test.py | 25 ++++++++++++------- 5 files changed, 47 insertions(+), 37 deletions(-) diff --git a/tests/README.md b/tests/README.md index e51a6a0e49..e990d622dc 100644 --- a/tests/README.md +++ b/tests/README.md @@ -81,7 +81,7 @@ Unit test script is the smallest testable part and developed for some function, ```bash cd debug/build/bin -./osTimeTests +./osTimeTests ``` ### How to run all unit test cases? @@ -163,12 +163,16 @@ cd /root/TDengine/packaging/smokeTest ## 3.3 Chaos Test -[Desciprtion] +A simple tool to exercise various functions of the system in a randomized fashion, hoping to expose maximum number of problems, hopefully without a pre-determined scenario. ### How to run test? -[Placeholder] +```bash +cd tests/pytest +python3 auto_crash_gen.py +``` ### How to add new case? -[Placeholder] +Add a function, such as TaskCreateNewFunction, to pytest/crash_gen/crash_gen_main.py. +Integrate TaskCreateNewFunction into the balance_pickTaskType function in crash_gen_main.py. diff --git a/tests/pytest/auto_crash_gen.py b/tests/pytest/auto_crash_gen.py index 316f2ead0f..a35beb3395 100755 --- a/tests/pytest/auto_crash_gen.py +++ b/tests/pytest/auto_crash_gen.py @@ -244,7 +244,7 @@ def start_taosd(): else: pass - start_cmd = 'cd %s && python3 test.py >>/dev/null '%(start_path) + start_cmd = 'cd %s && python3 test.py -G >>/dev/null '%(start_path) os.system(start_cmd) def get_cmds(args_list): @@ -371,7 +371,7 @@ Result: {msg_dict[status]} Details Owner: Jayden Jia Start time: {starttime} -End time: {endtime} +End time: {endtime} Hostname: {hostname} Commit: {git_commit} Cmd: {cmd} @@ -380,14 +380,13 @@ Core dir: {core_dir} ''' text_result=text.split("Result: ")[1].split("Details")[0].strip() print(text_result) - if text_result == "success": - send_msg(notification_robot_url, get_msg(text)) + send_msg(notification_robot_url, get_msg(text)) else: - send_msg(alert_robot_url, get_msg(text)) - send_msg(notification_robot_url, get_msg(text)) - - #send_msg(get_msg(text)) + send_msg(alert_robot_url, get_msg(text)) + send_msg(notification_robot_url, get_msg(text)) + + #send_msg(get_msg(text)) except Exception as e: print("exception:", e) exit(status) diff --git a/tests/pytest/auto_crash_gen_valgrind.py b/tests/pytest/auto_crash_gen_valgrind.py index b7af68cd2f..0bd70ebf3f 100755 --- a/tests/pytest/auto_crash_gen_valgrind.py +++ b/tests/pytest/auto_crash_gen_valgrind.py @@ -245,7 +245,7 @@ def start_taosd(): else: pass - start_cmd = 'cd %s && python3 test.py '%(start_path) + start_cmd = 'cd %s && python3 test.py -G'%(start_path) os.system(start_cmd +">>/dev/null") def get_cmds(args_list): @@ -404,24 +404,24 @@ Result: {msg_dict[status]} Details Owner: Jayden Jia Start time: {starttime} -End time: {endtime} +End time: {endtime} Hostname: {hostname} Commit: {git_commit} Cmd: {cmd} Log dir: {log_dir} Core dir: {core_dir} ''' - + text_result=text.split("Result: ")[1].split("Details")[0].strip() print(text_result) - + if text_result == "success": send_msg(notification_robot_url, get_msg(text)) else: - send_msg(alert_robot_url, get_msg(text)) + send_msg(alert_robot_url, get_msg(text)) send_msg(notification_robot_url, get_msg(text)) - - #send_msg(get_msg(text)) + + #send_msg(get_msg(text)) except Exception as e: print("exception:", e) exit(status) diff --git a/tests/pytest/auto_crash_gen_valgrind_cluster.py b/tests/pytest/auto_crash_gen_valgrind_cluster.py index df40b60967..b4b90e1f5e 100755 --- a/tests/pytest/auto_crash_gen_valgrind_cluster.py +++ b/tests/pytest/auto_crash_gen_valgrind_cluster.py @@ -236,7 +236,7 @@ def start_taosd(): else: pass - start_cmd = 'cd %s && python3 test.py -N 4 -M 1 '%(start_path) + start_cmd = 'cd %s && python3 test.py -N 4 -M 1 -G '%(start_path) os.system(start_cmd +">>/dev/null") def get_cmds(args_list): @@ -388,28 +388,28 @@ def main(): text = f''' Result: {msg_dict[status]} - + Details Owner: Jayden Jia Start time: {starttime} -End time: {endtime} +End time: {endtime} Hostname: {hostname} Commit: {git_commit} Cmd: {cmd} Log dir: {log_dir} Core dir: {core_dir} ''' - + text_result=text.split("Result: ")[1].split("Details")[0].strip() print(text_result) - + if text_result == "success": send_msg(notification_robot_url, get_msg(text)) else: - send_msg(alert_robot_url, get_msg(text)) - send_msg(notification_robot_url, get_msg(text)) - - #send_msg(get_msg(text)) + send_msg(alert_robot_url, get_msg(text)) + send_msg(notification_robot_url, get_msg(text)) + + #send_msg(get_msg(text)) except Exception as e: print("exception:", e) exit(status) diff --git a/tests/system-test/test.py b/tests/system-test/test.py index 0d40544be8..ab1bdc21d3 100644 --- a/tests/system-test/test.py +++ b/tests/system-test/test.py @@ -58,12 +58,12 @@ def checkRunTimeError(): if hwnd: os.system("TASKKILL /F /IM taosd.exe") -# +# # run case on previous cluster # def runOnPreviousCluster(host, config, fileName): print("enter run on previeous") - + # load case module sep = "/" if platform.system().lower() == 'windows': @@ -113,8 +113,9 @@ if __name__ == "__main__": asan = False independentMnode = False previousCluster = False - opts, args = getopt.gnu_getopt(sys.argv[1:], 'f:p:m:l:scghrd:k:e:N:M:Q:C:RWD:n:i:aP', [ - 'file=', 'path=', 'master', 'logSql', 'stop', 'cluster', 'valgrind', 'help', 'restart', 'updateCfgDict', 'killv', 'execCmd','dnodeNums','mnodeNums','queryPolicy','createDnodeNums','restful','websocket','adaptercfgupdate','replicaVar','independentMnode','previous']) + crashGen = False + opts, args = getopt.gnu_getopt(sys.argv[1:], 'f:p:m:l:scghrd:k:e:N:M:Q:C:RWD:n:i:aP:G', [ + 'file=', 'path=', 'master', 'logSql', 'stop', 'cluster', 'valgrind', 'help', 'restart', 'updateCfgDict', 'killv', 'execCmd','dnodeNums','mnodeNums','queryPolicy','createDnodeNums','restful','websocket','adaptercfgupdate','replicaVar','independentMnode','previous',"crashGen"]) for key, value in opts: if key in ['-h', '--help']: tdLog.printNoPrefix( @@ -141,6 +142,7 @@ if __name__ == "__main__": tdLog.printNoPrefix('-i independentMnode Mnode') tdLog.printNoPrefix('-a address sanitizer mode') tdLog.printNoPrefix('-P run case with [P]revious cluster, do not create new cluster to run case.') + tdLog.printNoPrefix('-G crashGen mode') sys.exit(0) @@ -208,7 +210,7 @@ if __name__ == "__main__": if key in ['-R', '--restful']: restful = True - + if key in ['-W', '--websocket']: websocket = True @@ -228,6 +230,10 @@ if __name__ == "__main__": if key in ['-P', '--previous']: previousCluster = True + if key in ['-G', '--crashGen']: + crashGen = True + + # # do exeCmd command # @@ -405,7 +411,7 @@ if __name__ == "__main__": for dnode in tdDnodes.dnodes: tdDnodes.starttaosd(dnode.index) tdCases.logSql(logSql) - + if restful or websocket: tAdapter.deploy(adapter_cfg_dict) tAdapter.start() @@ -450,7 +456,7 @@ if __name__ == "__main__": else: tdLog.debug(res) tdLog.exit(f"alter queryPolicy to {queryPolicy} failed") - + if ucase is not None and hasattr(ucase, 'noConn') and ucase.noConn == True: conn = None else: @@ -640,7 +646,7 @@ if __name__ == "__main__": else: tdLog.debug(res) tdLog.exit(f"alter queryPolicy to {queryPolicy} failed") - + # run case if testCluster: @@ -692,6 +698,7 @@ if __name__ == "__main__": # tdDnodes.StopAllSigint() tdLog.info("Address sanitizer mode finished") else: - tdDnodes.stopAll() + if not crashGen: + tdDnodes.stopAll() tdLog.info("stop all td process finished") sys.exit(0) From 376a30f20de579a29264587a2fc9c5f5d4f3ebdd Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Thu, 16 Jan 2025 17:00:39 +0800 Subject: [PATCH 36/56] update testing README by charles --- tests/README.md | 38 +++++++++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/tests/README.md b/tests/README.md index e990d622dc..78edcac6ac 100644 --- a/tests/README.md +++ b/tests/README.md @@ -57,11 +57,11 @@ In `tests` directory, there are different types of tests for TDengine. Below is ## 3.1 CI Test -[Desciprtion] +CI testing (Continuous Integration testing), is an important practice in software development that aims to automate frequent integration of code into a shared codebase, build and test it to ensure code quality and stability. TDengine CI testing includes three part of test cases: unit test、system test and legacy test -### How to run tests? +### How to run all CI test cases? -If this is the first time to run all the CI tests, it is recommended to add the test branch, please run like following commands: +If this is the first time to run all the CI test cases, it is recommended to add the test branch, please run it with following commands: ```bash cd tests @@ -70,8 +70,7 @@ cd tests ### How to add new cases? -[You can add sim test case under tests/script, python test case under tests/system-test or tests/army. When the case passes in the test branch, add the case to the cases.task file under tests/parallel_test, and then merge the pr into main branch to run in the future CI.] - +You can refer the below child sections to add new test cases for CI test. ### 3.1.1 Unit Test @@ -93,8 +92,27 @@ bash test.sh -e 0 #### How to add new cases? -Copy from the old version, need updates: +The Google test framwork is used for unit testing to specific function module, you can refer below steps to add one test case: +##### Create test case file and develop the test scripts + +In the test directory corresponding to the target function module, create test files in CPP format and write corresponding test cases. + +##### Update build configuration + +Modify the CMakeLists.txt file in this directory to ensure that the new test files are properly included in the compilation process. See the source\os\test\CMakeLists.txt file for configuration examples. + +##### Compile test code + +In the root directory of the project, create a compilation directory (e.g., debug), switch to the directory and run CMake commands (e.g., cmake .. -DBUILD_TEST=1) to generate a compilation file, and then run a compilation command (e.g. make) to complete the compilation of the test code. + +##### Execute the test program + +Find the executable file in the compiled directory(e.g. TDengine/debug/build/bin/) and run it. + +##### Integrate into CI tests + +Use the add_test command to add new compiled test cases into CI test collection, ensure that the new added test cases can be run for every build. ## 3.1.2 System Test @@ -141,14 +159,12 @@ cd tests ### How to add new case? -[Placeholder] - > [!NOTE] -> TSIM test framwork is replaced by system test currently, suggest to add new test scripts to system test. +> TSIM test framwork is replaced by system test currently, suggest to add new test scripts to system test, you can refer [System Test](#312-system-test) for detail steps. ## 3.2 Smoke Test -Smoke test script is known as sanity testing to ensure that the critical functionalities of TDengine. +Smoke test script is from system test and known as sanity testing to ensure that the critical functionalities of TDengine. ### How to run test? @@ -163,7 +179,7 @@ cd /root/TDengine/packaging/smokeTest ## 3.3 Chaos Test -A simple tool to exercise various functions of the system in a randomized fashion, hoping to expose maximum number of problems, hopefully without a pre-determined scenario. +A simple tool to exercise various functions of the system in a randomized fashion, hoping to expose maximum number of problems without a pre-determined scenario. ### How to run test? From b72e6189dac55857bf2d87d0d27a0f8e260ddf9c Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Thu, 16 Jan 2025 17:19:06 +0800 Subject: [PATCH 37/56] udpate smoke test part of testing README by charles --- tests/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/README.md b/tests/README.md index 78edcac6ac..ff42c9bb3d 100644 --- a/tests/README.md +++ b/tests/README.md @@ -175,7 +175,7 @@ cd /root/TDengine/packaging/smokeTest ### How to add new case? -[Placeholder] +You can update python commands part of test_smoking_selfhost.sh file to add any system test case into smoke test. ## 3.3 Chaos Test From ce384e325a9ed7f64e5e8dd3af78b509fa251935 Mon Sep 17 00:00:00 2001 From: chenhaoran Date: Thu, 16 Jan 2025 17:50:54 +0800 Subject: [PATCH 38/56] ci:modify test readme --- tests/README.md | 45 +++++++++++++-- .../0-others/test_case_template.py | 55 +++++++++++++++++++ 2 files changed, 94 insertions(+), 6 deletions(-) create mode 100644 tests/system-test/0-others/test_case_template.py diff --git a/tests/README.md b/tests/README.md index ff42c9bb3d..f684c8977c 100644 --- a/tests/README.md +++ b/tests/README.md @@ -92,28 +92,34 @@ bash test.sh -e 0 #### How to add new cases? +
+ +Detailed steps to add new unit test case + The Google test framwork is used for unit testing to specific function module, you can refer below steps to add one test case: -##### Create test case file and develop the test scripts +##### 1. Create test case file and develop the test scripts In the test directory corresponding to the target function module, create test files in CPP format and write corresponding test cases. -##### Update build configuration +##### 2. Update build configuration Modify the CMakeLists.txt file in this directory to ensure that the new test files are properly included in the compilation process. See the source\os\test\CMakeLists.txt file for configuration examples. -##### Compile test code +##### 3. Compile test code In the root directory of the project, create a compilation directory (e.g., debug), switch to the directory and run CMake commands (e.g., cmake .. -DBUILD_TEST=1) to generate a compilation file, and then run a compilation command (e.g. make) to complete the compilation of the test code. -##### Execute the test program +##### 4. Execute the test program Find the executable file in the compiled directory(e.g. TDengine/debug/build/bin/) and run it. -##### Integrate into CI tests +##### 5. Integrate into CI tests Use the add_test command to add new compiled test cases into CI test collection, ensure that the new added test cases can be run for every build. +
+ ## 3.1.2 System Test Python test script includes all of the functions of TDengine OSS, so some test case maybe fail cause the function only @@ -135,7 +141,34 @@ cd tests ### How to add new case? -[Placeholder] +
+ +Detailed steps to add new system test case + +you can refer below steps to add one test case: + +##### 1. Create test case file and develop the test scripts + +In the test directory corresponding to the target function module, create test files in CPP format and write corresponding test cases. + +##### 2. Update build configuration + +Modify the CMakeLists.txt file in this directory to ensure that the new test files are properly included in the compilation process. See the source\os\test\CMakeLists.txt file for configuration examples. + +##### 3. Compile test code + +In the root directory of the project, create a compilation directory (e.g., debug), switch to the directory and run CMake commands (e.g., cmake .. -DBUILD_TEST=1) to generate a compilation file, and then run a compilation command (e.g. make) to complete the compilation of the test code. + +##### 4. Execute the test program + +Find the executable file in the compiled directory(e.g. TDengine/debug/build/bin/) and run it. + +##### 5. Integrate into CI tests + +Use the add_test command to add new compiled test cases into CI test collection, ensure that the new added test cases can be run for every build. + +
+ ## 3.1.3 Legacy Test diff --git a/tests/system-test/0-others/test_case_template.py b/tests/system-test/0-others/test_case_template.py new file mode 100644 index 0000000000..53acbade66 --- /dev/null +++ b/tests/system-test/0-others/test_case_template.py @@ -0,0 +1,55 @@ + +from util.log import tdLog +from util.cases import tdCases +from util.sql import tdSql +from util.dnodes import tdDnodes +from util.dnodes import * +from util.common import * + + +class TDTestCase: + + """ + Here is the class description for the whole file cases + """ + + # add the configuration of the client and server here + clientCfgDict = {'debugFlag': 131} + updatecfgDict = { + "debugFlag" : "131", + "queryBufferSize" : 10240, + 'clientCfg' : clientCfgDict + } + + def init(self, conn, logSql, replicaVar=1): + tdLog.debug(f"start to excute {__file__}") + tdSql.init(conn.cursor()) + self.replicaVar = int(replicaVar) + + + def test_function(): # case function should be named start with test_ + """ + Here is the function description for single test: + Test case for custom function + """ + tdLog.info(f"Test case test custom function") + # excute the sql + tdLog.execute(f"create database db_test_function") + tdSql.execute(f"create table db_test_function.stb (ts timestamp, c1 int, c2 float, c3 double) tags (t1 int unsigned);") + # qury the result and return the result + tdSql.query(f"show databases") + # print result and check the result + database_info = tdLog.info(f"{tdSql.queryResult}") + tdSql.checkRows(3) + tdSql.checkData(2,0,"db_test_function") + + + def run(self): + self.test_5dnode_3mnode(dnodeNumbers=6,mnodeNums=3,restartNumbers=2,stopRole='vnode') + + def stop(self): + tdSql.close() + tdLog.success(f"{__file__} successfully executed") + +tdCases.addLinux(__file__, TDTestCase()) +tdCases.addWindows(__file__, TDTestCase()) From 24db39d4ce4a938baf8f5dce3b9ef427aa502fde Mon Sep 17 00:00:00 2001 From: Feng Chao Date: Thu, 16 Jan 2025 18:08:07 +0800 Subject: [PATCH 39/56] update testing guide structure by charles --- tests/README.md | 61 +++++++++++++++++++++++-------------------------- 1 file changed, 29 insertions(+), 32 deletions(-) diff --git a/tests/README.md b/tests/README.md index f684c8977c..4349e4bc65 100644 --- a/tests/README.md +++ b/tests/README.md @@ -3,13 +3,12 @@ 1. [Introduction](#1-introduction) 1. [Prerequisites](#2-prerequisites) 1. [Testing Guide](#3-testing-guide) - - [3.1 CI Test](#31-ci-test) - - [3.1.1 Unit Test](#311-unit-test) - - [3.1.2 System Test](#312-system-test) - - [3.1.3 Legacy Test](#313-legacy-test) - - [3.2 Smoke Test](#32-smoke-test) - - [3.3 Chaos Test](#33-chaos-test) - + - [3.1 Unit Test](#31-unit-test) + - [3.2 System Test](#32-system-test) + - [3.3 Legacy Test](#33-legacy-test) + - [3.4 Smoke Test](#34-smoke-test) + - [3.5 Chaos Test](#35-chaos-test) + - [3.6 CI Test](#36-ci-test) # 1. Introduction @@ -54,25 +53,7 @@ make && make install In `tests` directory, there are different types of tests for TDengine. Below is a brief introduction about how to run them and how to add new cases. - -## 3.1 CI Test - -CI testing (Continuous Integration testing), is an important practice in software development that aims to automate frequent integration of code into a shared codebase, build and test it to ensure code quality and stability. TDengine CI testing includes three part of test cases: unit test、system test and legacy test - -### How to run all CI test cases? - -If this is the first time to run all the CI test cases, it is recommended to add the test branch, please run it with following commands: - -```bash -cd tests -./run_all_ci_cases.sh -b main # on main branch -``` - -### How to add new cases? - -You can refer the below child sections to add new test cases for CI test. - -### 3.1.1 Unit Test +### 3.1 Unit Test Unit test script is the smallest testable part and developed for some function, method or class of TDengine. @@ -90,7 +71,7 @@ cd tests/unit-test/ bash test.sh -e 0 ``` -#### How to add new cases? +#### How to add new cases? {#test-id}
@@ -120,7 +101,7 @@ Use the add_test command to add new compiled test cases into CI test collection,
-## 3.1.2 System Test +## 3.2 System Test Python test script includes all of the functions of TDengine OSS, so some test case maybe fail cause the function only work for TDengine Enterprise Edition. @@ -169,8 +150,7 @@ Use the add_test command to add new compiled test cases into CI test collection, - -## 3.1.3 Legacy Test +## 3.3 Legacy Test In the early stage of TDengine development, test cases are run by an internal test framework called TSIM, which is developed in C++. @@ -195,7 +175,7 @@ cd tests > [!NOTE] > TSIM test framwork is replaced by system test currently, suggest to add new test scripts to system test, you can refer [System Test](#312-system-test) for detail steps. -## 3.2 Smoke Test +## 3.4 Smoke Test Smoke test script is from system test and known as sanity testing to ensure that the critical functionalities of TDengine. @@ -210,7 +190,7 @@ cd /root/TDengine/packaging/smokeTest You can update python commands part of test_smoking_selfhost.sh file to add any system test case into smoke test. -## 3.3 Chaos Test +## 3.5 Chaos Test A simple tool to exercise various functions of the system in a randomized fashion, hoping to expose maximum number of problems without a pre-determined scenario. @@ -225,3 +205,20 @@ python3 auto_crash_gen.py Add a function, such as TaskCreateNewFunction, to pytest/crash_gen/crash_gen_main.py. Integrate TaskCreateNewFunction into the balance_pickTaskType function in crash_gen_main.py. + +## 3.6 CI Test + +CI testing (Continuous Integration testing), is an important practice in software development that aims to automate frequent integration of code into a shared codebase, build and test it to ensure code quality and stability. TDengine CI testing includes three part of test cases: unit test、system test and legacy test + +### How to run all CI test cases? + +If this is the first time to run all the CI test cases, it is recommended to add the test branch, please run it with following commands: + +```bash +cd tests +./run_all_ci_cases.sh -b main # on main branch +``` + +### How to add new cases? + +You can refer the [Unit Test](#31-unit-test)、[System Test](#32-system-test) and [Legacy Test](#33-legacy-test) sections for detail steps to add new test cases for CI test. From 59ea64e1a8623ff6c54b7f9e45fb2241bf0190d9 Mon Sep 17 00:00:00 2001 From: chenhaoran Date: Thu, 16 Jan 2025 18:19:19 +0800 Subject: [PATCH 40/56] ci:modify test readme --- tests/README.md | 23 +++++++++---------- .../0-others/test_case_template.py | 6 ++--- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/tests/README.md b/tests/README.md index f684c8977c..9b903c2cb5 100644 --- a/tests/README.md +++ b/tests/README.md @@ -145,27 +145,26 @@ cd tests Detailed steps to add new system test case -you can refer below steps to add one test case: +test.py is the test case execution and monitoring of the entry program. you can refer below steps to add one test case: -##### 1. Create test case file and develop the test scripts +##### 1.Create a test case file and develop the test cases -In the test directory corresponding to the target function module, create test files in CPP format and write corresponding test cases. +Create a file in `tests/system-test` containing each functional directory and refer to the use case template `tests/system-test/0-others/test_case_template.py` to add a new test case. -##### 2. Update build configuration +##### 2.Execute the test case -Modify the CMakeLists.txt file in this directory to ensure that the new test files are properly included in the compilation process. See the source\os\test\CMakeLists.txt file for configuration examples. +cd tests/system-test & python3 ./test.py -f 0-others/test_case_template.py -##### 3. Compile test code +##### 3.Integrate into CI tests -In the root directory of the project, create a compilation directory (e.g., debug), switch to the directory and run CMake commands (e.g., cmake .. -DBUILD_TEST=1) to generate a compilation file, and then run a compilation command (e.g. make) to complete the compilation of the test code. +Edit `tests/parallel_test/cases.task` and add the testcase path and executions in the specified format. The third column indicates whether to use Address Sanitizer mode for testing. -##### 4. Execute the test program -Find the executable file in the compiled directory(e.g. TDengine/debug/build/bin/) and run it. -##### 5. Integrate into CI tests - -Use the add_test command to add new compiled test cases into CI test collection, ensure that the new added test cases can be run for every build. +```bash +#caseID,rerunTimes,Run with Sanitizer,casePath,caseCommand +,,n,system-test, python3 ./test.py -f 0-others/test_case_template.py +``` diff --git a/tests/system-test/0-others/test_case_template.py b/tests/system-test/0-others/test_case_template.py index 53acbade66..fa1a9b5ade 100644 --- a/tests/system-test/0-others/test_case_template.py +++ b/tests/system-test/0-others/test_case_template.py @@ -27,14 +27,14 @@ class TDTestCase: self.replicaVar = int(replicaVar) - def test_function(): # case function should be named start with test_ + def test_function(self): # case function should be named start with test_ """ Here is the function description for single test: Test case for custom function """ tdLog.info(f"Test case test custom function") # excute the sql - tdLog.execute(f"create database db_test_function") + tdSql.execute(f"create database db_test_function") tdSql.execute(f"create table db_test_function.stb (ts timestamp, c1 int, c2 float, c3 double) tags (t1 int unsigned);") # qury the result and return the result tdSql.query(f"show databases") @@ -45,7 +45,7 @@ class TDTestCase: def run(self): - self.test_5dnode_3mnode(dnodeNumbers=6,mnodeNums=3,restartNumbers=2,stopRole='vnode') + self.test_function() def stop(self): tdSql.close() From 31e69ea2b2c8ac2db72563f8aaf332c0a80cb69c Mon Sep 17 00:00:00 2001 From: chenhaoran Date: Thu, 16 Jan 2025 18:25:29 +0800 Subject: [PATCH 41/56] ci:modify test readme --- tests/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/README.md b/tests/README.md index 9b903c2cb5..fac0babe24 100644 --- a/tests/README.md +++ b/tests/README.md @@ -145,7 +145,8 @@ cd tests Detailed steps to add new system test case -test.py is the test case execution and monitoring of the entry program. you can refer below steps to add one test case: +The Python test framework is developed by TDengine teams, and test.py is the test case execution and monitoring of the entry program, Use `python3 ./test.py -h` to view more features. +you can refer below steps to add one test case: ##### 1.Create a test case file and develop the test cases From d155025d9d5067c79de7cb844bb99f5ae3118a1c Mon Sep 17 00:00:00 2001 From: chenhaoran Date: Thu, 16 Jan 2025 18:32:07 +0800 Subject: [PATCH 42/56] ci:modify test readme --- tests/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/README.md b/tests/README.md index fac0babe24..3bc57d67e3 100644 --- a/tests/README.md +++ b/tests/README.md @@ -154,7 +154,10 @@ Create a file in `tests/system-test` containing each functional directory and re ##### 2.Execute the test case +Ensure the test case execution is successful. +```bash cd tests/system-test & python3 ./test.py -f 0-others/test_case_template.py +``` ##### 3.Integrate into CI tests From 20f911d009ab106487d8b848d9f1fd2edcffae7e Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Thu, 16 Jan 2025 18:52:43 +0800 Subject: [PATCH 43/56] test:add note --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 91232136c5..8ceab44b3f 100644 --- a/README.md +++ b/README.md @@ -387,7 +387,10 @@ TDengine build check workflow can be found in this [Github Action](https://githu # 11. Coverage -Latest TDengine test coverage report can be found on [coveralls.io](https://coveralls.io/github/taosdata/TDengine). To create the test coverage report (in HTML format) locally, please run following commands: +
+ +Latest TDengine test coverage report can be found on [coveralls.io](https://coveralls.io/github/taosdata/TDengine). +To create the test coverage report (in HTML format) locally, please run following commands: ```bash cd tests @@ -395,9 +398,12 @@ bash setup-lcov.sh -v 1.16 && ./run_local_coverage.sh -b main -c task # on main branch and run cases in longtimeruning_cases.task # for more infomation about options please refer to ./run_local_coverage.sh -h ``` -> [!NOTE] +> [**NOTE**] > Please note that the -b and -i options will recompile TDengine with the -DCOVER=true option, which may take a amount of time. +
+ + # 12. Contributing Please follow the [contribution guidelines](CONTRIBUTING.md) to contribute to TDengine. From 469cbcbf332b972433f544d8340b8a8c2b16160d Mon Sep 17 00:00:00 2001 From: chenhaoran Date: Thu, 16 Jan 2025 18:56:49 +0800 Subject: [PATCH 44/56] ci:modify test readme --- README.md | 5 ++-- tests/README.md | 73 +++++++++++++++++++++++-------------------------- 2 files changed, 36 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 91232136c5..1111fc150f 100644 --- a/README.md +++ b/README.md @@ -138,8 +138,7 @@ git clone https://github.com/taosdata/TDengine.git cd TDengine ``` -> [!NOTE] -> TDengine Connectors can be found in following repositories: [JDBC Connector](https://github.com/taosdata/taos-connector-jdbc), [Go Connector](https://github.com/taosdata/driver-go), [Python Connector](https://github.com/taosdata/taos-connector-python), [Node.js Connector](https://github.com/taosdata/taos-connector-node), [C# Connector](https://github.com/taosdata/taos-connector-dotnet), [Rust Connector](https://github.com/taosdata/taos-connector-rust). +> NOTE: TDengine Connectors can be found in following repositories: [JDBC Connector](https://github.com/taosdata/taos-connector-jdbc), [Go Connector](https://github.com/taosdata/driver-go), [Python Connector](https://github.com/taosdata/taos-connector-python), [Node.js Connector](https://github.com/taosdata/taos-connector-node), [C# Connector](https://github.com/taosdata/taos-connector-dotnet), [Rust Connector](https://github.com/taosdata/taos-connector-rust). @@ -147,7 +146,7 @@ cd TDengine At the moment, TDengine server supports running on Linux/Windows/MacOS systems. Any application can also choose the RESTful interface provided by taosAdapter to connect the taosd service. TDengine supports X64/ARM64 CPU, and it will support MIPS64, Alpha64, ARM32, RISC-V and other CPU architectures in the future. Right now we don't support build with cross-compiling environment. -You can choose to install through source code, [container](https://docs.tdengine.com/get-started/docker/), [installation package](https://docs.tdengine.com/get-started/package/) or [Kubernetes](https://docs.tdengine.com/deployment/k8s/). This quick guide only applies to install from source. +You can choose to install through source code, [container](https://docs.tdengine.com/get-started/deploy-in-docker/), [installation package](https://docs.tdengine.com/get-started/deploy-from-package/) or [Kubernetes](https://docs.tdengine.com/operations-and-maintenance/deploy-your-cluster/#kubernetes-deployment). This quick guide only applies to install from source. TDengine provide a few useful tools such as taosBenchmark (was named taosdemo) and taosdump. They were part of TDengine. By default, TDengine compiling does not include taosTools. You can use `cmake .. -DBUILD_TOOLS=true` to make them be compiled with TDengine. diff --git a/tests/README.md b/tests/README.md index 3bc57d67e3..aef27c7a6e 100644 --- a/tests/README.md +++ b/tests/README.md @@ -3,13 +3,12 @@ 1. [Introduction](#1-introduction) 1. [Prerequisites](#2-prerequisites) 1. [Testing Guide](#3-testing-guide) - - [3.1 CI Test](#31-ci-test) - - [3.1.1 Unit Test](#311-unit-test) - - [3.1.2 System Test](#312-system-test) - - [3.1.3 Legacy Test](#313-legacy-test) - - [3.2 Smoke Test](#32-smoke-test) - - [3.3 Chaos Test](#33-chaos-test) - + - [3.1 Unit Test](#31-unit-test) + - [3.2 System Test](#32-system-test) + - [3.3 Legacy Test](#33-legacy-test) + - [3.4 Smoke Test](#34-smoke-test) + - [3.5 Chaos Test](#35-chaos-test) + - [3.6 CI Test](#36-ci-test) # 1. Introduction @@ -54,25 +53,7 @@ make && make install In `tests` directory, there are different types of tests for TDengine. Below is a brief introduction about how to run them and how to add new cases. - -## 3.1 CI Test - -CI testing (Continuous Integration testing), is an important practice in software development that aims to automate frequent integration of code into a shared codebase, build and test it to ensure code quality and stability. TDengine CI testing includes three part of test cases: unit test、system test and legacy test - -### How to run all CI test cases? - -If this is the first time to run all the CI test cases, it is recommended to add the test branch, please run it with following commands: - -```bash -cd tests -./run_all_ci_cases.sh -b main # on main branch -``` - -### How to add new cases? - -You can refer the below child sections to add new test cases for CI test. - -### 3.1.1 Unit Test +### 3.1 Unit Test Unit test script is the smallest testable part and developed for some function, method or class of TDengine. @@ -90,7 +71,7 @@ cd tests/unit-test/ bash test.sh -e 0 ``` -#### How to add new cases? +#### How to add new cases?
@@ -104,15 +85,15 @@ In the test directory corresponding to the target function module, create test f ##### 2. Update build configuration -Modify the CMakeLists.txt file in this directory to ensure that the new test files are properly included in the compilation process. See the source\os\test\CMakeLists.txt file for configuration examples. +Modify the CMakeLists.txt file in this directory to ensure that the new test files are properly included in the compilation process. See the `source/os/test/CMakeLists.txt` file for configuration examples. ##### 3. Compile test code -In the root directory of the project, create a compilation directory (e.g., debug), switch to the directory and run CMake commands (e.g., cmake .. -DBUILD_TEST=1) to generate a compilation file, and then run a compilation command (e.g. make) to complete the compilation of the test code. +In the root directory of the project, create a compilation directory (e.g., debug), switch to the directory and run CMake commands (e.g., `cmake .. -DBUILD_TEST=1`) to generate a compilation file, and then run a compilation command (e.g. make) to complete the compilation of the test code. ##### 4. Execute the test program -Find the executable file in the compiled directory(e.g. TDengine/debug/build/bin/) and run it. +Find the executable file in the compiled directory(e.g. `TDengine/debug/build/bin/`) and run it. ##### 5. Integrate into CI tests @@ -120,7 +101,7 @@ Use the add_test command to add new compiled test cases into CI test collection,
-## 3.1.2 System Test +## 3.2 System Test Python test script includes all of the functions of TDengine OSS, so some test case maybe fail cause the function only work for TDengine Enterprise Edition. @@ -154,10 +135,7 @@ Create a file in `tests/system-test` containing each functional directory and re ##### 2.Execute the test case -Ensure the test case execution is successful. -```bash cd tests/system-test & python3 ./test.py -f 0-others/test_case_template.py -``` ##### 3.Integrate into CI tests @@ -172,8 +150,7 @@ Edit `tests/parallel_test/cases.task` and add the testcase path and executions i - -## 3.1.3 Legacy Test +## 3.3 Legacy Test In the early stage of TDengine development, test cases are run by an internal test framework called TSIM, which is developed in C++. @@ -195,10 +172,10 @@ cd tests ### How to add new case? -> [!NOTE] +> [!NOTE] > TSIM test framwork is replaced by system test currently, suggest to add new test scripts to system test, you can refer [System Test](#312-system-test) for detail steps. -## 3.2 Smoke Test +## 3.4 Smoke Test Smoke test script is from system test and known as sanity testing to ensure that the critical functionalities of TDengine. @@ -213,7 +190,7 @@ cd /root/TDengine/packaging/smokeTest You can update python commands part of test_smoking_selfhost.sh file to add any system test case into smoke test. -## 3.3 Chaos Test +## 3.5 Chaos Test A simple tool to exercise various functions of the system in a randomized fashion, hoping to expose maximum number of problems without a pre-determined scenario. @@ -227,4 +204,22 @@ python3 auto_crash_gen.py ### How to add new case? Add a function, such as TaskCreateNewFunction, to pytest/crash_gen/crash_gen_main.py. + Integrate TaskCreateNewFunction into the balance_pickTaskType function in crash_gen_main.py. + +## 3.6 CI Test + +CI testing (Continuous Integration testing), is an important practice in software development that aims to automate frequent integration of code into a shared codebase, build and test it to ensure code quality and stability. TDengine CI testing includes three part of test cases: unit test、system test and legacy test + +### How to run all CI test cases? + +If this is the first time to run all the CI test cases, it is recommended to add the test branch, please run it with following commands: + +```bash +cd tests +./run_all_ci_cases.sh -b main # on main branch +``` + +### How to add new cases? + +You can refer the [Unit Test](#31-unit-test)、[System Test](#32-system-test) and [Legacy Test](#33-legacy-test) sections for detail steps to add new test cases for CI test. From 51f989833bba2ae7495d24ab4c4e3cbdd2da1fae Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Thu, 16 Jan 2025 18:59:37 +0800 Subject: [PATCH 45/56] test:add note --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8ceab44b3f..872842423c 100644 --- a/README.md +++ b/README.md @@ -398,7 +398,7 @@ bash setup-lcov.sh -v 1.16 && ./run_local_coverage.sh -b main -c task # on main branch and run cases in longtimeruning_cases.task # for more infomation about options please refer to ./run_local_coverage.sh -h ``` -> [**NOTE**] +> **NOTE:** > Please note that the -b and -i options will recompile TDengine with the -DCOVER=true option, which may take a amount of time. From 687fa1d5c272d4959bb62f4afb4ebd809bc82f85 Mon Sep 17 00:00:00 2001 From: happyguoxy Date: Thu, 16 Jan 2025 19:01:09 +0800 Subject: [PATCH 46/56] test:add note --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 872842423c..8ef4f1e887 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,7 @@ git clone https://github.com/taosdata/TDengine.git cd TDengine ``` -> [!NOTE] +> **NOTE:** > TDengine Connectors can be found in following repositories: [JDBC Connector](https://github.com/taosdata/taos-connector-jdbc), [Go Connector](https://github.com/taosdata/driver-go), [Python Connector](https://github.com/taosdata/taos-connector-python), [Node.js Connector](https://github.com/taosdata/taos-connector-node), [C# Connector](https://github.com/taosdata/taos-connector-dotnet), [Rust Connector](https://github.com/taosdata/taos-connector-rust). From 4f0335eb9976d5b88bbf515b7f75f924f22217ad Mon Sep 17 00:00:00 2001 From: chenhaoran Date: Thu, 16 Jan 2025 19:03:14 +0800 Subject: [PATCH 47/56] ci:modify test readme --- tests/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/README.md b/tests/README.md index aef27c7a6e..b9fa40f93b 100644 --- a/tests/README.md +++ b/tests/README.md @@ -173,7 +173,7 @@ cd tests ### How to add new case? > [!NOTE] -> TSIM test framwork is replaced by system test currently, suggest to add new test scripts to system test, you can refer [System Test](#312-system-test) for detail steps. +> TSIM test framwork is replaced by system test currently, suggest to add new test scripts to system test, you can refer [System Test](#32-system-test) for detail steps. ## 3.4 Smoke Test From 0af9f1005435f003606914d62e560e0836a370ba Mon Sep 17 00:00:00 2001 From: chenhaoran Date: Thu, 16 Jan 2025 19:10:10 +0800 Subject: [PATCH 48/56] Merge latest changes from origin/docs/chr1-readme --- tests/README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/tests/README.md b/tests/README.md index b9fa40f93b..bc97d74afd 100644 --- a/tests/README.md +++ b/tests/README.md @@ -12,7 +12,9 @@ # 1. Introduction -This manual is intended to provide users with comprehensive guidance to help them verify the TDengine function efficiently. The document is divided into three main sections: introduction, prerequisites and testing guide. +This manual is intended to provide users with comprehensive guidance to help them verify the TDengine function efficiently. + +The document is divided into three main sections: introduction, prerequisites and testing guide. > [!NOTE] > The below commands and test scripts are verified on linux (Ubuntu 18.04、20.04、22.04) locally. @@ -89,7 +91,9 @@ Modify the CMakeLists.txt file in this directory to ensure that the new test fil ##### 3. Compile test code -In the root directory of the project, create a compilation directory (e.g., debug), switch to the directory and run CMake commands (e.g., `cmake .. -DBUILD_TEST=1`) to generate a compilation file, and then run a compilation command (e.g. make) to complete the compilation of the test code. +In the root directory of the project, create a compilation directory (e.g., debug), switch to the directory and run CMake commands (e.g., `cmake .. -DBUILD_TEST=1`) to generate a compilation file, + +and then run a compilation command (e.g. make) to complete the compilation of the test code. ##### 4. Execute the test program @@ -110,7 +114,7 @@ work for TDengine Enterprise Edition. ```bash cd tests/system-test -python3 ./test.py -f 2-query/floor.py +python3 ./test.py -f 2-query/avg.py ``` ### How to run all system test cases? @@ -127,6 +131,7 @@ cd tests Detailed steps to add new system test case The Python test framework is developed by TDengine teams, and test.py is the test case execution and monitoring of the entry program, Use `python3 ./test.py -h` to view more features. + you can refer below steps to add one test case: ##### 1.Create a test case file and develop the test cases @@ -209,7 +214,9 @@ Integrate TaskCreateNewFunction into the balance_pickTaskType function in crash_ ## 3.6 CI Test -CI testing (Continuous Integration testing), is an important practice in software development that aims to automate frequent integration of code into a shared codebase, build and test it to ensure code quality and stability. TDengine CI testing includes three part of test cases: unit test、system test and legacy test +CI testing (Continuous Integration testing), is an important practice in software development that aims to automate frequent integration of code into a shared codebase, build and test it to ensure code quality and stability. + +TDengine CI testing includes three part of test cases: unit test、system test and legacy test ### How to run all CI test cases? From 35f8fb8153f615d71cb2277d381ab75ea57464d9 Mon Sep 17 00:00:00 2001 From: chenhaoran Date: Thu, 16 Jan 2025 19:11:36 +0800 Subject: [PATCH 49/56] ci:modify test readme --- tests/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/README.md b/tests/README.md index bc97d74afd..5574a16743 100644 --- a/tests/README.md +++ b/tests/README.md @@ -140,7 +140,10 @@ Create a file in `tests/system-test` containing each functional directory and re ##### 2.Execute the test case +Ensure the test case execution is successful. +``` bash cd tests/system-test & python3 ./test.py -f 0-others/test_case_template.py +``` ##### 3.Integrate into CI tests From 7d2d44cbe328110c12b87cfca340ed6ca33573b4 Mon Sep 17 00:00:00 2001 From: chenhaoran Date: Thu, 16 Jan 2025 19:25:12 +0800 Subject: [PATCH 50/56] ci:modify test readme --- README.md | 4 +++- tests/README.md | 46 +++++++++++++++++++++++----------------------- 2 files changed, 26 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 787c5c6b7a..a7009fb6f2 100644 --- a/README.md +++ b/README.md @@ -388,9 +388,11 @@ TDengine build check workflow can be found in this [Github Action](https://githu # 11. Coverage +Latest TDengine test coverage report can be found on [coveralls.io](https://coveralls.io/github/taosdata/TDengine) +
-Latest TDengine test coverage report can be found on [coveralls.io](https://coveralls.io/github/taosdata/TDengine). + how to run the coverage report locally. To create the test coverage report (in HTML format) locally, please run following commands: ```bash diff --git a/tests/README.md b/tests/README.md index 5574a16743..dd1f8ba9a1 100644 --- a/tests/README.md +++ b/tests/README.md @@ -59,21 +59,21 @@ In `tests` directory, there are different types of tests for TDengine. Below is Unit test script is the smallest testable part and developed for some function, method or class of TDengine. -### How to run single test case? +### 3.1.1 How to run single test case? ```bash cd debug/build/bin ./osTimeTests ``` -### How to run all unit test cases? +### 3.1.2 How to run all unit test cases? ```bash cd tests/unit-test/ bash test.sh -e 0 ``` -#### How to add new cases? +### 3.1.3 How to add new cases?
@@ -81,25 +81,25 @@ bash test.sh -e 0 The Google test framwork is used for unit testing to specific function module, you can refer below steps to add one test case: -##### 1. Create test case file and develop the test scripts +##### a. Create test case file and develop the test scripts In the test directory corresponding to the target function module, create test files in CPP format and write corresponding test cases. -##### 2. Update build configuration +##### b. Update build configuration Modify the CMakeLists.txt file in this directory to ensure that the new test files are properly included in the compilation process. See the `source/os/test/CMakeLists.txt` file for configuration examples. -##### 3. Compile test code +##### c. Compile test code In the root directory of the project, create a compilation directory (e.g., debug), switch to the directory and run CMake commands (e.g., `cmake .. -DBUILD_TEST=1`) to generate a compilation file, and then run a compilation command (e.g. make) to complete the compilation of the test code. -##### 4. Execute the test program +##### d. Execute the test program Find the executable file in the compiled directory(e.g. `TDengine/debug/build/bin/`) and run it. -##### 5. Integrate into CI tests +##### e. Integrate into CI tests Use the add_test command to add new compiled test cases into CI test collection, ensure that the new added test cases can be run for every build. @@ -110,21 +110,21 @@ Use the add_test command to add new compiled test cases into CI test collection, Python test script includes all of the functions of TDengine OSS, so some test case maybe fail cause the function only work for TDengine Enterprise Edition. -### How to run single test case? +### 3.2.1 How to run single test case? ```bash cd tests/system-test python3 ./test.py -f 2-query/avg.py ``` -### How to run all system test cases? +### 3.2.2 How to run all system test cases? ```bash cd tests ./run_all_ci_cases.sh -t python # all python cases ``` -### How to add new case? +### 3.2.3 How to add new case?
@@ -134,18 +134,18 @@ The Python test framework is developed by TDengine teams, and test.py is the tes you can refer below steps to add one test case: -##### 1.Create a test case file and develop the test cases +##### a. Create a test case file and develop the test cases Create a file in `tests/system-test` containing each functional directory and refer to the use case template `tests/system-test/0-others/test_case_template.py` to add a new test case. -##### 2.Execute the test case +##### b. Execute the test case Ensure the test case execution is successful. ``` bash cd tests/system-test & python3 ./test.py -f 0-others/test_case_template.py ``` -##### 3.Integrate into CI tests +##### c. Integrate into CI tests Edit `tests/parallel_test/cases.task` and add the testcase path and executions in the specified format. The third column indicates whether to use Address Sanitizer mode for testing. @@ -162,7 +162,7 @@ Edit `tests/parallel_test/cases.task` and add the testcase path and executions i In the early stage of TDengine development, test cases are run by an internal test framework called TSIM, which is developed in C++. -### How to run single test case? +### 3.3.1 How to run single test case? To run the legacy test cases, please execute the following commands: @@ -171,14 +171,14 @@ cd tests/script ./test.sh -f tsim/db/basic1.sim ``` -### How to run all legacy test cases? +### 3.3.2 How to run all legacy test cases? ```bash cd tests ./run_all_ci_cases.sh -t legacy # all legacy cases ``` -### How to add new case? +### 3.3.3 How to add new case? > [!NOTE] > TSIM test framwork is replaced by system test currently, suggest to add new test scripts to system test, you can refer [System Test](#32-system-test) for detail steps. @@ -187,14 +187,14 @@ cd tests Smoke test script is from system test and known as sanity testing to ensure that the critical functionalities of TDengine. -### How to run test? +### 3.4.1 How to run test? ```bash cd /root/TDengine/packaging/smokeTest ./test_smoking_selfhost.sh ``` -### How to add new case? +### 3.4.2 How to add new case? You can update python commands part of test_smoking_selfhost.sh file to add any system test case into smoke test. @@ -202,14 +202,14 @@ You can update python commands part of test_smoking_selfhost.sh file to add any A simple tool to exercise various functions of the system in a randomized fashion, hoping to expose maximum number of problems without a pre-determined scenario. -### How to run test? +### 3.5.1 How to run test? ```bash cd tests/pytest python3 auto_crash_gen.py ``` -### How to add new case? +### 3.5.2 How to add new case? Add a function, such as TaskCreateNewFunction, to pytest/crash_gen/crash_gen_main.py. @@ -221,7 +221,7 @@ CI testing (Continuous Integration testing), is an important practice in softwar TDengine CI testing includes three part of test cases: unit test、system test and legacy test -### How to run all CI test cases? +### 3.6.1 How to run all CI test cases? If this is the first time to run all the CI test cases, it is recommended to add the test branch, please run it with following commands: @@ -230,6 +230,6 @@ cd tests ./run_all_ci_cases.sh -b main # on main branch ``` -### How to add new cases? +### 3.6.2 How to add new cases? You can refer the [Unit Test](#31-unit-test)、[System Test](#32-system-test) and [Legacy Test](#33-legacy-test) sections for detail steps to add new test cases for CI test. From f54ee09915172a2545c1facfa6ba5086d79ea17c Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Thu, 16 Jan 2025 20:51:37 +0800 Subject: [PATCH 51/56] Update README.md --- tests/README.md | 53 +++++++++++++++++++++++-------------------------- 1 file changed, 25 insertions(+), 28 deletions(-) diff --git a/tests/README.md b/tests/README.md index dd1f8ba9a1..26ced3da17 100644 --- a/tests/README.md +++ b/tests/README.md @@ -12,12 +12,10 @@ # 1. Introduction -This manual is intended to provide users with comprehensive guidance to help them verify the TDengine function efficiently. - -The document is divided into three main sections: introduction, prerequisites and testing guide. +This manual is intended to give developers a comprehensive guidance to test TDengine efficiently. It is divided into three main sections: introduction, prerequisites and testing guide. > [!NOTE] -> The below commands and test scripts are verified on linux (Ubuntu 18.04、20.04、22.04) locally. +> The commands and scripts below are verified on Linux (Ubuntu 18.04/20.04/22.04). # 2. Prerequisites @@ -43,7 +41,7 @@ pip3 install taospy taos-ws-py - Building -Please make sure building operation with option `-DBUILD_TOOLS=true -DBUILD_TEST=true -DBUILD_CONTRIB=true` has been finished, otherwise execute commands below: +Before testting, please make sure the building operation with option `-DBUILD_TOOLS=true -DBUILD_TEST=true -DBUILD_CONTRIB=true` has been done, otherwise execute commands below: ```bash cd debug @@ -57,7 +55,7 @@ In `tests` directory, there are different types of tests for TDengine. Below is ### 3.1 Unit Test -Unit test script is the smallest testable part and developed for some function, method or class of TDengine. +Unit tests are the smallest testable units, which are used to test functions, methods or classes in TDengine code. ### 3.1.1 How to run single test case? @@ -79,7 +77,7 @@ bash test.sh -e 0 Detailed steps to add new unit test case -The Google test framwork is used for unit testing to specific function module, you can refer below steps to add one test case: +The Google test framwork is used for unit testing to specific function module, please refer to steps below to add a new test case: ##### a. Create test case file and develop the test scripts @@ -107,10 +105,11 @@ Use the add_test command to add new compiled test cases into CI test collection, ## 3.2 System Test -Python test script includes all of the functions of TDengine OSS, so some test case maybe fail cause the function only -work for TDengine Enterprise Edition. +System tests are end-to-end test cases written in Python from a system point of view. Some of them are designed to test features only in enterprise ediiton, so when running on community edition, they may fail. We'll fix this issue by separating the cases into different gruops in the future. -### 3.2.1 How to run single test case? +### 3.2.1 How to run a single test case? + +Take test file `system-test/2-query/avg.py` for example: ```bash cd tests/system-test @@ -130,9 +129,9 @@ cd tests Detailed steps to add new system test case -The Python test framework is developed by TDengine teams, and test.py is the test case execution and monitoring of the entry program, Use `python3 ./test.py -h` to view more features. +The Python test framework is developed by TDengine team, and test.py is the test case execution and monitoring of the entry program, Use `python3 ./test.py -h` to view more features. -you can refer below steps to add one test case: +Please refer to steps below for how to add a new test case: ##### a. Create a test case file and develop the test cases @@ -141,16 +140,15 @@ Create a file in `tests/system-test` containing each functional directory and re ##### b. Execute the test case Ensure the test case execution is successful. + ``` bash -cd tests/system-test & python3 ./test.py -f 0-others/test_case_template.py +cd tests/system-test && python3 ./test.py -f 0-others/test_case_template.py ``` ##### c. Integrate into CI tests Edit `tests/parallel_test/cases.task` and add the testcase path and executions in the specified format. The third column indicates whether to use Address Sanitizer mode for testing. - - ```bash #caseID,rerunTimes,Run with Sanitizer,casePath,caseCommand ,,n,system-test, python3 ./test.py -f 0-others/test_case_template.py @@ -178,14 +176,14 @@ cd tests ./run_all_ci_cases.sh -t legacy # all legacy cases ``` -### 3.3.3 How to add new case? +### 3.3.3 How to add new cases? > [!NOTE] -> TSIM test framwork is replaced by system test currently, suggest to add new test scripts to system test, you can refer [System Test](#32-system-test) for detail steps. +> TSIM test framwork is deprecated by system test now, it is encouraged to add new test cases in system test, please refer to [System Test](#32-system-test) for details. ## 3.4 Smoke Test -Smoke test script is from system test and known as sanity testing to ensure that the critical functionalities of TDengine. +Smoke test is a group of test cases selected from system test, which is also known as sanity test to ensure the critical functionalities of TDengine. ### 3.4.1 How to run test? @@ -194,13 +192,13 @@ cd /root/TDengine/packaging/smokeTest ./test_smoking_selfhost.sh ``` -### 3.4.2 How to add new case? +### 3.4.2 How to add new cases? -You can update python commands part of test_smoking_selfhost.sh file to add any system test case into smoke test. +New cases can be added by updating the value of `commands` variable in `test_smoking_selfhost.sh`. ## 3.5 Chaos Test -A simple tool to exercise various functions of the system in a randomized fashion, hoping to expose maximum number of problems without a pre-determined scenario. +A simple tool to execute various functions of the system in a randomized way, hoping to expose potential problems without a pre-defined test scenario. ### 3.5.1 How to run test? @@ -209,21 +207,20 @@ cd tests/pytest python3 auto_crash_gen.py ``` -### 3.5.2 How to add new case? +### 3.5.2 How to add new cases? -Add a function, such as TaskCreateNewFunction, to pytest/crash_gen/crash_gen_main.py. - -Integrate TaskCreateNewFunction into the balance_pickTaskType function in crash_gen_main.py. +1. Add a function, such as `TaskCreateNewFunction` in `pytest/crash_gen/crash_gen_main.py`. +2. Integrate `TaskCreateNewFunction` into the `balance_pickTaskType` function in `crash_gen_main.py`. ## 3.6 CI Test CI testing (Continuous Integration testing), is an important practice in software development that aims to automate frequent integration of code into a shared codebase, build and test it to ensure code quality and stability. -TDengine CI testing includes three part of test cases: unit test、system test and legacy test +TDengine CI testing will run all the test cases from the following three types of tests: unit test, system test and legacy test. ### 3.6.1 How to run all CI test cases? -If this is the first time to run all the CI test cases, it is recommended to add the test branch, please run it with following commands: +If this is the first time to run all the CI test cases, it is recommended to add the test branch, please run it with following commands: ```bash cd tests @@ -232,4 +229,4 @@ cd tests ### 3.6.2 How to add new cases? -You can refer the [Unit Test](#31-unit-test)、[System Test](#32-system-test) and [Legacy Test](#33-legacy-test) sections for detail steps to add new test cases for CI test. +Please refer to the [Unit Test](#31-unit-test)、[System Test](#32-system-test) and [Legacy Test](#33-legacy-test) sections for detailed steps to add new test cases, when new cases are added in aboved tests, they will be run automatically by CI test. From a6d343cdb8ce1d7de3c4cde6e21285b1a63663a0 Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Thu, 16 Jan 2025 20:56:47 +0800 Subject: [PATCH 52/56] Update README.md --- tests/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/README.md b/tests/README.md index 26ced3da17..23b2ca8700 100644 --- a/tests/README.md +++ b/tests/README.md @@ -41,7 +41,7 @@ pip3 install taospy taos-ws-py - Building -Before testting, please make sure the building operation with option `-DBUILD_TOOLS=true -DBUILD_TEST=true -DBUILD_CONTRIB=true` has been done, otherwise execute commands below: +Before testing, please make sure the building operation with option `-DBUILD_TOOLS=true -DBUILD_TEST=true -DBUILD_CONTRIB=true` has been done, otherwise execute commands below: ```bash cd debug From f2ae4a042565db54011de9909f861bde65a15f23 Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Thu, 16 Jan 2025 21:11:39 +0800 Subject: [PATCH 53/56] Update README.md --- tests/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/README.md b/tests/README.md index 23b2ca8700..58747d93f7 100644 --- a/tests/README.md +++ b/tests/README.md @@ -15,7 +15,8 @@ This manual is intended to give developers a comprehensive guidance to test TDengine efficiently. It is divided into three main sections: introduction, prerequisites and testing guide. > [!NOTE] -> The commands and scripts below are verified on Linux (Ubuntu 18.04/20.04/22.04). +> - The commands and scripts below are verified on Linux (Ubuntu 18.04/20.04/22.04). +> - The commands and steps described below are to run the tests on a single host. # 2. Prerequisites From 1fb80a3b2580855cd7632b9a079f722375644eb4 Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Thu, 16 Jan 2025 21:15:15 +0800 Subject: [PATCH 54/56] Update README.md --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index a7009fb6f2..53ddc85bf9 100644 --- a/README.md +++ b/README.md @@ -243,7 +243,7 @@ nmake # 5. Packaging -TDengine packaging scripts depends on some private repositries currently, you can refer the link for detail steps. [Packaging](https://github.com/taosdata/TDinternal/tree/main?tab=readme-ov-file#5-packaging) +[Placeholder] # 6. Installation @@ -406,7 +406,6 @@ bash setup-lcov.sh -v 1.16 && ./run_local_coverage.sh -b main -c task
- # 12. Contributing Please follow the [contribution guidelines](CONTRIBUTING.md) to contribute to TDengine. From d95a1ca89a661d68f21a16f8b21569872ccd700e Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Thu, 16 Jan 2025 21:16:56 +0800 Subject: [PATCH 55/56] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 53ddc85bf9..a09b9cfea3 100644 --- a/README.md +++ b/README.md @@ -384,7 +384,7 @@ For the complete list of TDengine Releases, please see [Releases](https://github # 10. Workflow -TDengine build check workflow can be found in this [Github Action](https://github.com/taosdata/TDengine/actions/workflows/taosd-ci-build.yml). +TDengine build check workflow can be found in this [Github Action](https://github.com/taosdata/TDengine/actions/workflows/taosd-ci-build.yml). More workflows will be available soon. # 11. Coverage From 5b95b519ee4f9553e81ff69176222ee1a6589aea Mon Sep 17 00:00:00 2001 From: WANG Xu Date: Fri, 17 Jan 2025 14:05:22 +0800 Subject: [PATCH 56/56] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a09b9cfea3..f540b1cc43 100644 --- a/README.md +++ b/README.md @@ -243,7 +243,7 @@ nmake # 5. Packaging -[Placeholder] +The TDengine community installer can NOT be created by this repository only, due to some component dependencies. We are still working on this improvement. # 6. Installation @@ -392,7 +392,7 @@ Latest TDengine test coverage report can be found on [coveralls.io](https://cove
- how to run the coverage report locally. +How to run the coverage report locally? To create the test coverage report (in HTML format) locally, please run following commands: ```bash