README.md

# Maps Booking

This repo contains tools and code samples for partners that wish to integrate
with [Reserve](https://www.google.com/maps/reserve/) API v3.

## Testing Client

Before using either the order based or booking based test utilites, the Go
programming language must be installed on your workstation. A precompiled Go
binary for your operating system can be [found here](https://golang.org/dl/)

This guide will assume you're using the default GOPATH and subsequent GOBIN.
For a comprehensive explanation of the GOPATH env variable please see
[this document](https://golang.org/dl/) by the Go team.

### Installing the utilities with Linux

First, build your Go directory structure. A comprehensive guide on the intended
structure of Go code can be [found here.](https://golang.org/doc/code.html)

    mkdir -p $HOME/go/bin $HOME/go/pkg $HOME/go/src/github.com/maps-booking-v3

Next, add the following to your ~/.bashrc

    export PATH=$PATH:$(go env GOPATH)/bin
    export GOPATH=$(go env GOPATH)
    export GOBIN=$(go env GOPATH)/bin

Source changes

    source ~/.bashrc

Remove any files from a previous installation

    rm -rf $HOME/go/src/github.com/maps-booking-v3/

Next, retrieve the utilities from the
[maps-booking-v3 repository](https://maps-booking.googlesource.com/)

    git clone https://maps-booking.googlesource.com/maps-booking-v3 $HOME/go/src/github.com/maps-booking-v3/

Download all dependencies

    cd $HOME/go
    go get -d ./...

If installing the order based test client, run

    go install $HOME/go/src/github.com/maps-booking-v3/testclient/orderClient.go

Or the booking based test client, run

    go install $HOME/go/src/github.com/maps-booking-v3/testclient/bookingClient.go

### Installing the utilities with Windows Powershell

First, build your Go directory structure. A comprehensive guide on the intended
structure of Go code can be [found here.](https://golang.org/doc/code.html)

    $env:HOME = $env:USERPROFILE
    md $env:HOME\go\bin
    md $env:HOME\go\pkg
    md $env:HOME\go\src\github.com\maps-booking-v3

Next, set the appropriate environment variables

    $env:PATH = $env:PATH + ";" + (go env GOPATH) + "\bin"
    $env:GOPATH = (go env GOPATH)
    $env:GOBIN = (go env GOPATH) + "\bin"

Remove any files from a previous installation

    rd -r $env:HOME\go\src\github.com\maps-booking-v3\

Next, retrieve the utilities from the
[maps-booking-v3 repository](https://maps-booking.googlesource.com/)

    git clone https://maps-booking.googlesource.com/maps-booking-v3 $env:HOME\go\src\github.com\maps-booking-v3\

Download all dependencies

    cd $env:HOME\go
    go get -d .\...

If installing the order based test client, run

    go install $env:HOME\go\src\github.com\maps-booking-v3\testclient\orderClient.go

Or the booking based test client, run

    go install $env:HOME\go\src\github.com\maps-booking-v3\testclient\bookingClient.go

### Using the utilities

After following the install steps above an executable should now live under the
path

    $HOME/go/bin/

or

    $env:HOME\go\bin\

All available flags can be displayed using the '--help' flag. The currently
accepted flags are:

    bookingClient.go
    -all_tests
        Whether to test all endpoints.
    -availability_feed string
        Absolute path to availability feed required for all tests except health.
        Feeds can be in either json or pb3 format
    -booking_status_test
        Whether to test the GetBookingStatus endpoint.
    -booking_test
        Whether to test the CreateBooking endpoint.
    -cancel_all_bookings
        This option assumes that the ListBookings and UpdateBooking endpoints
        are fully functional. This is a convenience flag for purging your system
        of all previously created bookings.
    -check_availability_test
        Whether to test the CheckAvailability endpoint.
    -health_check_test
        Whether to test the Health endpoint.
    -list_bookings_test
        Whether to test the ListBookings endpoint
    -num_test_slots int
        Maximum number of slots to test from availability_feed. Slots will be
        selected randomly (default 10)
    -output_dir string
        Absolute path of dir to dump log file.
    -rescheduling_test
        Whether to test the UpdateBooking endpoint.
    -server_addr string
        Your http server's address in the format of host:port
        (default "localhost:443")
    -credentials_file string
        File containing credentials for your server. Leave blank to bypass authentication.
        File should have exactly one line of the form 'username:password'.
    -ca_file string
        Absolute path to your server's Certificate Authority root cert.
        Downloading all roots currently recommended by the Google Internet
        Authority is a suitable alternative https://pki.google.com/roots.pem.
        Leave blank to connect using http rather than https.
    -full_server_name string
        Fully qualified domain name. Same name used to sign CN. Only necessary if ca_file is specified and the base URL differs from the server address.
    -output_to_terminal bool
        Output to terminal rather than a file.

    orderClient.go
    -all_tests
        Whether to test all endpoints syncronously, including ListOrders flow.
    -availability_feed string
        Absolute path to availability feed required for all tests except health. Feeds can be in either json or pb3 format
    -ca_file string
        Absolute path to your server's Certificate Authority root cert. Downloading all roots currently recommended by the Google Internet Authority is a suitable alternative https://pki.google.com/roots.pem. Leave blank to connect using http rather than https.
    -check_order_test
        Whether to test the CheckOrderFulfillability endpoint.
    -create_order_test
        Whether to test the CreateOrder endpoint.
    -credentials_file string
        File containing credentials for your server. Leave blank to bypass authentication. File should have exactly one line of the form 'username:password'.
    -full_server_name string
        Fully qualified domain name. Same name used to sign CN. Only necessary if ca_file is specified and the base URL differs from the server address.
    -health_check_test
        Whether to test the Health endpoint.
    -num_test_slots int
        Maximum number of slots to test from availability_feed. Slots will be selected randomly (default 10)
    -output_dir string
        Absolute path of dir to dump log file.
    -server_addr string
        Your http server's address in the format of host:port (default "example.com:80")
    -service_feed string
        Absolute path to service feed required for all tests except health. Feeds can be in either json or pb3 format
    -output_to_terminal bool
        Output to terminal rather than a file.

Example Usage:

    bin/bookingClient -server_addr="localhost:443" -check_availability_test=true -output_dir="/tmp" -availability_feed="/tmp/test.json"

    bin/orderClient -server_addr="external-dns:443" -all_tests=true -output_dir="/tmp" -availability_feed="/tmp/test.json" -service_feed="/tmp/service.json"

### Testing

It is important that as part of testing you verify all aspects of booking server
invocation - authentication, availability, cancellation, and rescheduling tests.
As the final step, you must be able to execute the designated utility with the
flag -all_tests=true and it should successfully pass the entire series of tests.

### Parsing the output

Both test utilities will output a file with the prefix 'http_test_client_log_'
followed by a timestamp in RFC3339 format. The output file contains a
complete log of all Requests and Responses sent/received by the testing tool as
well as diffs of the expected response in the event of errors.
Similar to a compiler, an overview of the entire run can be found at the end
of the file for user friendly digestion.