diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ea58b981..8e16c8ed 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -2,14 +2,14 @@ name: tests on: push: - branches: [ master ] + branches: [ main ] paths-ignore: - docs/* - '**/*.md' - test/*.go pull_request: - branches: [ master ] + branches: [ main ] jobs: diff --git a/.gitignore b/.gitignore index 4ac60955..65521094 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ test/c8y_test/application.properties test/c8y_test/debug.test test/c8y_test/application.setup.properties c8y.env +*.env main.exe *.log output diff --git a/README.md b/README.md index ae91dff7..79b828ce 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # go-c8y -Unofficial Go client for [Cumulocity](http://cumulocity.com/guides/reference/rest-implementation/). +Unofficial Go client for [Cumulocity IoT](https://cumulocity.com/api/core/). ![tests](https://github.com/reubenmiller/go-c8y/workflows/tests/badge.svg) [![Go Report Card](https://goreportcard.com/badge/github.com/reubenmiller/go-c8y)](https://goreportcard.com/report/github.com/reubenmiller/go-c8y) @@ -11,50 +11,18 @@ Unofficial Go client for [Cumulocity](http://cumulocity.com/guides/reference/res We encourage you to try the package in your projects, just keep these caveats in mind, please: -* **This is a work in progress.** Not all of the Cumulocity REST API is covered, and the HTTP client is very simple. In the future the HTTP Client will be improved to support retries on failures, client side rate limiting, prometheus api metrics, mqtt client. +* **This is a work in progress.** Not all of the Cumulocity IoT REST API is covered, and the HTTP client is very simple. In the future the HTTP Client will be improved to support retries on failures, client side rate limiting, prometheus api metrics, mqtt client. -* **There are no guarantees on API stability.** The general mechanics of the golang API are still being worked out. The balance between helpers and clarity is still being found. Given limited access to all available Cumulocity Servers versions, compatibility to all Cumulocity versions is not guarenteed, however since Cumulocity takes an additive approach to new features, it is more likely that the new features will be missing rather than existing API breaking (excluding deprecated features) +* **There are no guarantees on API stability.** The general mechanics of the golang API are still being worked out. The balance between helpers and clarity is still being found. Given limited access to all available Cumulocity IoT versions, compatibility to all Cumulocity IoT versions is not guaranteed, however since Cumulocity IoT takes an additive approach to new features, it is more likely that the new features will be missing rather than existing API breaking (excluding deprecated features) +## Usage - -## Installation - -Install the package with `go get`: - - go get -u github.com/reubenmiller/go-c8y/c8y_test - -Or, add the package to your `go.mod` file: - - require github.com/reubenmiller/go-c8y/c8y_test master - -Or, clone the repository: - - git clone https://github.com/reubenmiller/go-c8y/c8y_test.git && cd go-c8y - - -## Running the tests - -1. Create an `application.properties` file in the `./c8y_test` folder and set the Cumulocity host, tenant and user credentials. The user must have admin rights in the specified tenant. - - ```sh - c8y.host= - c8y.tenant= - c8y.username= - c8y.password= - testing.cleanup.removeDevice=false - ``` - -2. Execute the integration tests +1. Add the package to your project using `go get`: ```sh - go test -timeout 30s github.com/reubenmiller/go-c8y/c8y_test - - # race detector. Onlwindows use backslashes - go test -race -timeout 30s github.com/reubenmiller/go-c8y/test/c8y_test -run "^(TestRealtimeSubscriptions_Unsubscribe)$ + go get -u github.com/reubenmiller/go-c8y/c8y ``` -## Usage - 1. Create a `main.go` file with the following ```golang @@ -89,26 +57,53 @@ Or, clone the repository: } ``` -2. Execute the application +2. Set the credentials via environment variables + + **Windows (PowerShell)** - On Windows ```sh - set C8Y_HOST=https://cumulocity.com - set C8Y_TENANT=mycompany - set C8Y_USER=username - set C8Y_PASSWORD=password - go run main.go + $env:C8Y_HOST = "https://cumulocity.com" + $env:C8Y_TENANT = "mycompany" + $env:C8Y_USER = "username" + $env:C8Y_PASSWORD = "password" ``` - On Linux/MacOS + **Linux/MacOS** + ```sh export C8Y_HOST=https://cumulocity.com export C8Y_TENANT=mycompany export C8Y_USER=username export C8Y_PASSWORD=password + ``` + +3. Run the application + + ```sh go run main.go ``` ## Examples More examples can be found under the `examples` folder. + +## Development + +### Running the tests + +To run the tests you will need to install [go-task](https://taskfile.dev/installation/), or use the dev container which includes go-task. + +1. Create a dotenv file `.env` to the root folder and add your Cumulocity credentials to use for the tests + + ```sh + C8Y_HOST=https://cumulocity.com + C8Y_TENANT=mycompany + C8Y_USER=username + C8Y_PASSWORD=password + ``` + +2. Execute the tests + + ```sh + task test + ``` diff --git a/Taskfile.yml b/Taskfile.yml index a53de8de..dc6fd05b 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -3,7 +3,7 @@ version: '3' env: ENV: testing -dotenv: ['c8y.env', '{{.ENV}}/c8y.env', '{{.HOME}}/c8y.env'] +dotenv: ['.env', 'c8y.env', '{{.ENV}}/c8y.env', '{{.HOME}}/c8y.env'] tasks: test: @@ -11,6 +11,7 @@ tasks: cmds: - task: test-c8y - task: test-microservice + - task: test-race test-c8y: desc: Test c8y package @@ -22,6 +23,11 @@ tasks: cmds: - go test -v -timeout 30m github.com/reubenmiller/go-c8y/test/microservice_test + test-race: + desc: Test for race conditions + cmds: + - go test -race -timeout 30s github.com/reubenmiller/go-c8y/test/c8y_test -run "^(TestRealtimeSubscriptions_Unsubscribe)$" + lint: desc: Linting cmds: