coveralls

README

go-coveralls-api

Client for Coveralls API written in Go.

Note: the goal is to interact with administrative Coveralls API. To send coverage data, take a look at goveralls project.

Installation

Just follow the usual instructions for Go libraries:

go get github.com/loadsmart/go-coveralls-api

go-coveralls-api uses Go Modules and therefore requires Go 1.11+.

Usage

To get the ID of a repo already configured in Coveralls

import (
    "context"
    "fmt"
    "log"

    "github.com/loadsmart/go-coveralls-api"
)

client := coveralls.NewClient("your-personal-access-token")
repository, err := client.Repositories.Get(context.Background(), "github", "user/repository")
if err != nil {
    log.Fatalf("Error querying Coveralls API: %s\n", err)
}

fmt.Printf("Project has ID %d in Coveralls", repository.ID)

Replace your-personal-access-token with your personal access token (can be found in your Coveralls account page).

License

This work is copyrighted to Loadsmart, Inc. and licensed under MIT. For details see LICENSE file.

Documentation

Overview

Package coveralls provide functions to interact with Coveralls API

Index

• Variables
• type Client
  • func NewClient(t string) *Client
• type ErrUnexpectedStatusCode
  • func (e ErrUnexpectedStatusCode) Error() string
• type ErrUnprocessableEntity
  • func (e ErrUnprocessableEntity) Error() string
• type Repository
• type RepositoryConfig
• type RepositoryService
• type RepositoryServiceImpl
  • func (s RepositoryServiceImpl) Add(ctx context.Context, data *RepositoryConfig) (*RepositoryConfig, error)
  • func (s RepositoryServiceImpl) Get(ctx context.Context, svc string, repo string) (*Repository, error)
  • func (s RepositoryServiceImpl) Update(ctx context.Context, svc string, repo string, data *RepositoryConfig) (*RepositoryConfig, error)

Variables

var (
	// ErrRepoNotFound is returned when we receive a 404 Not Found status code
	ErrRepoNotFound = fmt.Errorf("repo was not found (status code %d)", http.StatusNotFound)

	// ErrNameIsTaken is returned when the API respondes to a POST saying that the repo
	// name has already been taken. The status code is UnprocessableEntity but we return
	// this more specific error for convenience.
	ErrNameIsTaken = fmt.Errorf("unprocessable entity (status code %d): repo name has already been taken", http.StatusUnprocessableEntity)
)

Types

type Client

type Client struct {

	// Host URL for Coveralls. Defaults to https://coveralls.io
	// Change this if you want to use private Coveralls server (untested)
	HostURL      *url.URL
	Repositories RepositoryService // Service to interact with repository-related endpoints
	// contains filtered or unexported fields
}

Client is used to provide a single interface to interact with Coveralls API

func NewClient

func NewClient(t string) *Client

NewClient returns a new Coveralls API Client t is the Coveralls API token

type ErrUnexpectedStatusCode

type ErrUnexpectedStatusCode struct {
	StatusCode int
	ErrorBody  string
}

ErrUnexpectedStatusCode is returned when we receive an unexpected status code, not covered by our other sentinel errors.

func (ErrUnexpectedStatusCode) Error

func (e ErrUnexpectedStatusCode) Error() string

type ErrUnprocessableEntity

type ErrUnprocessableEntity struct {
	ErrorBody string
}

ErrUnprocessableEntity is returned when the API returns 422 Unprocessable Entity status code and we don't have identified a more specific error condition.

Its error message string includes the full body from the response. That includes some error in the RepositoryConfig spec, but may include other conditions.

func (ErrUnprocessableEntity) Error

func (e ErrUnprocessableEntity) Error() string

type Repository

type Repository struct {
	ID                              int      `json:"id,omitempty"`
	Name                            string   `json:"name,omitempty"`
	Service                         string   `json:"service,omitempty"`                             // Git provider. Options include: github, bitbucket, gitlab, stash, manual
	CommentOnPullRequests           *bool    `json:"comment_on_pull_requests,omitempty"`            // Whether comments should be posted on pull requests (defaults to true)
	SendBuildStatus                 *bool    `json:"send_build_status,omitempty"`                   // Whether build status should be sent to the git provider (defaults to true)
	CommitStatusFailThreshold       *float64 `json:"commit_status_fail_threshold,omitempty"`        // Minimum coverage that must be present on a build for the build to pass (default is null, meaning any decrease is a failure)
	CommitStatusFailChangeThreshold *float64 `json:"commit_status_fail_change_threshold,omitempty"` // If coverage decreases, the maximum allowed amount of decrease that will be allowed for the build to pass (default is null, meaning that any decrease is a failure)
	HasBadge                        bool     `json:"has_badge,omitempty"`
	Token                           string   `json:"token,omitempty"`
	CreatedAt                       string   `json:"created_at,omitempty"`
	UpdatedAt                       string   `json:"updated_at,omitempty"`
}

Repository holds information about one specific repository

type RepositoryConfig

type RepositoryConfig struct {
	Service                         string   `json:"service"`                                       // Git provider. Options include: github, bitbucket, gitlab, stash, manual
	Name                            string   `json:"name"`                                          // Name of the repo. E.g. with Github, this is username/reponame.
	CommentOnPullRequests           *bool    `json:"comment_on_pull_requests,omitempty"`            // Whether comments should be posted on pull requests (defaults to true)
	SendBuildStatus                 *bool    `json:"send_build_status,omitempty"`                   // Whether build status should be sent to the git provider (defaults to true)
	CommitStatusFailThreshold       *float64 `json:"commit_status_fail_threshold,omitempty"`        // Minimum coverage that must be present on a build for the build to pass (default is null, meaning any decrease is a failure)
	CommitStatusFailChangeThreshold *float64 `json:"commit_status_fail_change_threshold,omitempty"` // If coverage decreases, the maximum allowed amount of decrease that will be allowed for the build to pass (default is null, meaning that any decrease is a failure)
}

RepositoryConfig represents config settings for a given repository

type RepositoryService

type RepositoryService interface {
	Get(ctx context.Context, svc string, repo string) (*Repository, error)
	Add(ctx context.Context, data *RepositoryConfig) (*RepositoryConfig, error)
	Update(ctx context.Context, svc string, repo string, data *RepositoryConfig) (*RepositoryConfig, error)
}

RepositoryService holds information to access repository-related endpoints

type RepositoryServiceImpl

type RepositoryServiceImpl service

RepositoryServiceImpl holds information to access repository-related endpoints

func (RepositoryServiceImpl) Add

func (s RepositoryServiceImpl) Add(ctx context.Context, data *RepositoryConfig) (*RepositoryConfig, error)

Add a repository to Coveralls

It may return errors ErrNameIsTaken, ErrUnprocessableEntity or ErrUnexpectedStatusCode

func (RepositoryServiceImpl) Get

func (s RepositoryServiceImpl) Get(ctx context.Context, svc string, repo string) (*Repository, error)

Get information about a repository already in Coveralls.

Ctx is a context that's propagated to underlying client. You can use it to cancel the request in progress (when the program is terminated, for example).

Svc indicates the service. Any value accepted by Coveralls API can be passed here. Soma valid inputs include 'github', 'bitbucket' or 'manual'.

Repo is the repository name. In GitHub, for example, this is 'organization/repository'; other services could have different formats.

If the request succeeded, it returns a Repository with the information available or an error if there was something wrong.

It may return errors ErrRepoNotFound or ErrUnexpectedStatusCode

func (RepositoryServiceImpl) Update

func (s RepositoryServiceImpl) Update(ctx context.Context, svc string, repo string, data *RepositoryConfig) (*RepositoryConfig, error)

Update repository configuration in Coveralls

It may return errors ErrRepoNotFound, ErrUnprocessableEntity or ErrUnexpectedStatusCode