# 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

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/

Lastly, download all dependencies and install the tool.

    cd $HOME/go
    go get -d ./...
    go install $HOME/go/src/github.com/maps-booking-v3/testclient/<orderBasedTestClient.go or bookingBasedTestClient.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"

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\

Lastly, download all dependencies and install the tool.

    cd $env:HOME\go
    go get -d .\...
    go install $env:HOME\go\src\github.com\maps-booking-v3\testclient\<orderBasedTestClient.go or bookingBasedTestClient.go>

### Using the utilities

After following the install steps above an executable should now live in

    $HOME/go/bin/main

or

    $env:HOME\go\bin\main.exe

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

    bookingBasedTestClient.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.

    orderBasedTestClient.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

Example Usage:

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

    bin/main -server_addr="external-dns:443" -all_tests=true -output_dir="/tmp" -availability_feed="/tmp/test.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.