api_e2e_utils.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef QA_API_E2E_UTILS_H
#define QA_API_E2E_UTILS_H
 
#include <chrono>
#include <functional>
#include <string>
#include <vector>
 
#include <google/protobuf/any.pb.h>
#include <magic_enum.hpp>
#include <wx/filename.h>
#include <wx/process.h>
#include <wx/stream.h>
#include <wx/utils.h>
 
#ifdef __UNIX__
#include <signal.h>
#include <sys/wait.h>
#include <unistd.h>
#endif
 
#include <api/api_client.h>
#include <api/api_utils.h>
#include <api/common/envelope.pb.h>
#include <api/common/commands/base_commands.pb.h>
#include <api/common/commands/editor_commands.pb.h>
#include <api/common/commands/project_commands.pb.h>
#include <api/common/types/base_types.pb.h>
#include <api/common/types/enums.pb.h>
#include <api/common/types/jobs.pb.h>
#include <footprint.h>
#include <pcbnew_utils/board_file_utils.h>
#include <qa_utils/wx_utils/unit_test_utils.h>
#include <wx/log.h>
 
 
#ifndef QA_KICAD_CLI_PATH
#define QA_KICAD_CLI_PATH "kicad-cli"
#endif
 
 
class API_SERVER_PROCESS : public wxProcess
{
public:
    API_SERVER_PROCESS( std::function<void( int, const wxString&, const wxString& )> aCallback ) :
            wxProcess(),
            m_callback( std::move( aCallback ) )
    {
    }
 
    void OnTerminate( int aPid, int aStatus ) override
    {
        wxString output;
        wxString error;
 
        drainStream( GetInputStream(), output );
        drainStream( GetErrorStream(), error );
 
        if( m_callback )
            m_callback( aStatus, output, error );
    }
 
    static void drainStream( wxInputStream* aStream, wxString& aDest )
    {
        if( !aStream || !aStream->CanRead() )
            return;
 
        constexpr size_t chunkSize = 1024;
        char             buffer[chunkSize + 1] = { 0 };
 
        while( aStream->CanRead() )
        {
            aStream->Read( buffer, chunkSize );
            size_t bytesRead = aStream->LastRead();
 
            if( bytesRead == 0 )
                break;
 
            buffer[bytesRead] = '\0';
            aDest += wxString::FromUTF8( buffer );
        }
    }
 
private:
    std::function<void( int, const wxString&, const wxString& )> m_callback;
};
 
 
class API_TEST_CLIENT
{
public:
    API_TEST_CLIENT() : m_client( 10000 ) {}
 
    bool Connect( const wxString& aSocketUrl ) { return m_client.Connect( aSocketUrl ); }
    void Disconnect() { m_client.Disconnect(); }
 
    const wxString& LastError() const { return m_lastError; }
 
    bool Ping( kiapi::common::ApiStatusCode* aStatusOut = nullptr )
    {
        kiapi::common::commands::Ping ping;
        kiapi::common::ApiResponse    response;
 
        if( !send( ping, response ) )
            return false;
 
        if( aStatusOut )
            *aStatusOut = response.status().status();
 
        return true;
    }
 
    bool GetVersion()
    {
        kiapi::common::commands::GetVersion request;
        kiapi::common::ApiResponse          response;
 
        if( !send( request, response ) )
            return false;
 
        if( response.status().status() != kiapi::common::AS_OK )
        {
            m_lastError = response.status().error_message();
            return false;
        }
 
        kiapi::common::commands::GetVersionResponse version;
 
        if( !response.message().UnpackTo( &version ) )
        {
            m_lastError = wxS( "Failed to unpack GetVersionResponse" );
            return false;
        }
 
        return true;
    }
 
    bool OpenDocument( const wxString& aPath, kiapi::common::types::DocumentType aType,
                       kiapi::common::types::DocumentSpecifier* aDocument = nullptr )
    {
        kiapi::common::commands::OpenDocument request;
        request.set_type( aType );
        request.set_path( aPath.ToStdString() );
 
        kiapi::common::ApiResponse response;
 
        if( !send( request, response ) )
            return false;
 
        if( response.status().status() != kiapi::common::AS_OK )
        {
            m_lastError = response.status().error_message();
            return false;
        }
 
        kiapi::common::commands::OpenDocumentResponse openResponse;
 
        if( !response.message().UnpackTo( &openResponse ) )
        {
            m_lastError = wxS( "Failed to unpack OpenDocumentResponse" );
            return false;
        }
 
        if( aDocument )
            *aDocument = openResponse.document();
 
        return true;
    }
 
    bool CreateDocument( const wxString& aPath, kiapi::common::types::DocumentType aType,
                         kiapi::common::types::DocumentSpecifier* aDocument = nullptr )
    {
        kiapi::common::commands::CreateDocument request;
        request.set_type( aType );
        request.set_path( aPath.ToStdString() );
 
        kiapi::common::ApiResponse response;
 
        if( !send( request, response ) )
            return false;
 
        if( response.status().status() != kiapi::common::AS_OK )
        {
            m_lastError = response.status().error_message();
            return false;
        }
 
        kiapi::common::commands::OpenDocumentResponse openResponse;
 
        if( !response.message().UnpackTo( &openResponse ) )
        {
            m_lastError = wxS( "Failed to unpack OpenDocumentResponse" );
            return false;
        }
 
        if( aDocument )
            *aDocument = openResponse.document();
 
        return true;
    }
 
    // Convenience overload for PCB documents (backward compatible)
    bool OpenDocument( const wxString& aPath, kiapi::common::types::DocumentSpecifier* aDocument = nullptr )
    {
        return OpenDocument( aPath, kiapi::common::types::DOCTYPE_PCB, aDocument );
    }
 
    bool GetItemsCount( const kiapi::common::types::DocumentSpecifier& aDocument,
                        kiapi::common::types::KiCadObjectType aType, int* aCount )
    {
        kiapi::common::commands::GetItems request;
        *request.mutable_header()->mutable_document() = aDocument;
        request.add_types( aType );
 
        kiapi::common::ApiResponse response;
 
        if( !send( request, response ) )
            return false;
 
        if( response.status().status() != kiapi::common::AS_OK )
        {
            m_lastError = response.status().error_message();
            return false;
        }
 
        kiapi::common::commands::GetItemsResponse itemsResponse;
 
        if( !response.message().UnpackTo( &itemsResponse ) )
        {
            m_lastError = wxS( "Failed to unpack GetItemsResponse" );
            return false;
        }
 
        if( itemsResponse.status() != kiapi::common::types::IRS_OK )
        {
            m_lastError = wxString::Format( wxS( "GetItems returned non-OK status: %d" ),
                                            static_cast<int>( itemsResponse.status() ) );
            return false;
        }
 
        *aCount = itemsResponse.items_size();
        return true;
    }
 
    bool GetFirstFootprint( const kiapi::common::types::DocumentSpecifier& aDocument, FOOTPRINT* aFootprint )
    {
        wxCHECK( aFootprint, false );
 
        kiapi::common::commands::GetItems request;
        *request.mutable_header()->mutable_document() = aDocument;
        request.add_types( kiapi::common::types::KOT_PCB_FOOTPRINT );
 
        kiapi::common::ApiResponse response;
 
        if( !send( request, response ) )
        {
            m_lastError = wxS( "Failed to send command" );
            return false;
        }
 
        if( response.status().status() != kiapi::common::AS_OK )
        {
            m_lastError = response.status().error_message();
            return false;
        }
 
        kiapi::common::commands::GetItemsResponse itemsResponse;
 
        if( !response.message().UnpackTo( &itemsResponse ) )
        {
            m_lastError = wxS( "Failed to unpack GetItemsResponse" );
            return false;
        }
 
        if( itemsResponse.status() != kiapi::common::types::IRS_OK )
        {
            m_lastError = wxString::Format( wxS( "GetItems returned non-OK status: %s" ),
                                            magic_enum::enum_name( itemsResponse.status() ) );
            return false;
        }
 
        if( itemsResponse.items_size() == 0 )
        {
            m_lastError = wxS( "GetItems returned no footprints" );
            return false;
        }
 
        if( !aFootprint->Deserialize( itemsResponse.items( 0 ) ) )
        {
            m_lastError = wxS( "Failed to deserialize first footprint from GetItems response" );
            return false;
        }
 
        return true;
    }

    bool GetFootprintByReference( const kiapi::common::types::DocumentSpecifier& aDocument, const wxString& aReference,
                                  FOOTPRINT* aFootprint )
    {
        wxCHECK( aFootprint, false );
 
        kiapi::common::commands::GetItems request;
        *request.mutable_header()->mutable_document() = aDocument;
        request.add_types( kiapi::common::types::KOT_PCB_FOOTPRINT );
 
        kiapi::common::ApiResponse response;
 
        if( !send( request, response ) )
        {
            m_lastError = wxS( "Failed to send command" );
            return false;
        }
 
        if( response.status().status() != kiapi::common::AS_OK )
        {
            m_lastError = response.status().error_message();
            return false;
        }
 
        kiapi::common::commands::GetItemsResponse itemsResponse;
 
        if( !response.message().UnpackTo( &itemsResponse ) )
        {
            m_lastError = wxS( "Failed to unpack GetItemsResponse" );
            return false;
        }
 
        if( itemsResponse.status() != kiapi::common::types::IRS_OK )
        {
            m_lastError = wxString::Format( wxS( "GetItems returned non-OK status: %s" ),
                                            magic_enum::enum_name( itemsResponse.status() ) );
            return false;
        }
 
        for( const google::protobuf::Any& item : itemsResponse.items() )
        {
            FOOTPRINT candidate( nullptr );
 
            if( !candidate.Deserialize( item ) )
                continue;
 
            const PCB_FIELD* reference = std::as_const( candidate ).GetField( FIELD_T::REFERENCE );
 
            if( reference && reference->GetText() == aReference )
            {
                *aFootprint = std::move( candidate );
                return true;
            }
        }
 
        m_lastError = wxS( "No footprint with reference " ) + aReference;
        return false;
    }
 
    bool CloseDocument( const kiapi::common::types::DocumentSpecifier* aDocument,
                        kiapi::common::ApiStatusCode*                  aStatus = nullptr )
    {
        kiapi::common::commands::CloseDocument request;
 
        if( aDocument )
            *request.mutable_document() = *aDocument;
 
        kiapi::common::ApiResponse response;
 
        if( !send( request, response ) )
        {
            m_lastError = wxS( "Failed to send command" );
            return false;
        }
 
        if( aStatus )
            *aStatus = response.status().status();
 
        if( response.status().status() != kiapi::common::AS_OK )
            m_lastError = response.status().error_message();
 
        return true;
    }
 
    bool CloseAllDocuments()
    {
        kiapi::common::commands::CloseAllDocuments request;
        kiapi::common::ApiResponse                 response;
 
        if( !send( request, response ) )
            return false;
 
        if( response.status().status() != kiapi::common::AS_OK )
        {
            m_lastError = response.status().error_message();
            return false;
        }
 
        return true;
    }

    template <typename T>
    bool RunJob( const T& aJobRequest, kiapi::common::types::RunJobResponse* aResponse )
    {
        kiapi::common::ApiResponse apiResponse;
 
        if( !send( aJobRequest, apiResponse ) )
            return false;
 
        if( apiResponse.status().status() != kiapi::common::AS_OK )
        {
            m_lastError = apiResponse.status().error_message();
            return false;
        }
 
        if( !apiResponse.message().UnpackTo( aResponse ) )
        {
            m_lastError = wxS( "Failed to unpack RunJobResponse" );
            return false;
        }
 
        return true;
    }
 
    template <typename T>
    bool SendCommand( const T& aMessage, kiapi::common::ApiResponse* aResponse )
    {
        return send( aMessage, *aResponse );
    }
 
private:
    bool send( const google::protobuf::Message& aRequest, kiapi::common::ApiResponse& aResponse )
    {
        if( !m_client.Send( aRequest, aResponse, "kicad.qa" ) )
        {
            m_lastError = m_client.GetLastError();
            return false;
        }
 
        return true;
    }
 
    KICAD_API_CLIENT m_client;
    wxString         m_lastError;
};
 

class API_SERVER_MANAGER
{
public:
    static API_SERVER_MANAGER& Instance()
    {
        static API_SERVER_MANAGER s_instance;
        return s_instance;
    }

    bool EnsureReady( const wxString& aCliPath, wxString* aError )
    {
        if( m_ready )
        {
            if( isProcessAlive() )
            {
                // A new testcase is starting up, make sure old things are closed
                Client().CloseAllDocuments();
                return true;
            }
 
            m_ready = false;
        }
 
        BOOST_TEST_MESSAGE( "Starting API server with CLI path: " << aCliPath );
 
        if( !startServerProcess( aCliPath, aError ) )
            return false;
 
        if( !connectAndWaitReady( aError ) )
            return false;
 
        m_ready = true;
        return true;
    }
 
    API_TEST_CLIENT& Client() { return m_client; }

    void Reset()
    {
        m_ready = false;
        m_client.Disconnect();
 
        if( m_pid != 0 && isProcessAlive() )
        {
#ifdef __WXMAC__
            wxProcess::Kill( m_pid, wxSIGKILL );
#else
            wxProcess::Kill( m_pid, wxSIGKILL, wxKILL_CHILDREN );
#endif
        }
 
        m_pid = 0;
        m_process = nullptr;
 
        if( wxFileName::Exists( m_socketPath ) )
            wxRemoveFile( m_socketPath );
    }
 
private:
    API_SERVER_MANAGER()
    {
#ifdef __UNIX__
        m_socketPath = wxString::Format( wxS( "/tmp/kicad-api-e2e-%ld.sock" ), wxGetProcessId() );
#else
        wxString tempPath = wxFileName::CreateTempFileName( wxS( "kicad-api-e2e" ) );
 
        if( wxFileExists( tempPath ) )
            wxRemoveFile( tempPath );
 
        m_socketPath = tempPath + wxS( ".sock" );
#endif
 
        m_socketUrl = wxS( "ipc://" ) + m_socketPath;
 
        if( wxFileName::Exists( m_socketPath ) )
            wxRemoveFile( m_socketPath );
    }
 
    ~API_SERVER_MANAGER()
    {
        // Use POSIX primitives here because this destructor runs during static destruction
        // when wxWidgets may already be partially torn down.
#ifdef __UNIX__
        if( m_pid != 0 )
        {
            kill( static_cast<pid_t>( m_pid ), SIGTERM );
            usleep( 200000 );
            kill( static_cast<pid_t>( m_pid ), SIGKILL );
        }
 
        if( !m_socketPath.IsEmpty() )
            unlink( m_socketPath.ToUTF8().data() );
#else
        if( m_pid != 0 )
            wxProcess::Kill( m_pid, wxSIGKILL, wxKILL_CHILDREN );
 
        if( !m_socketPath.IsEmpty() && wxFileName::Exists( m_socketPath ) )
            wxRemoveFile( m_socketPath );
#endif
    }
 
    API_SERVER_MANAGER( const API_SERVER_MANAGER& ) = delete;
    API_SERVER_MANAGER& operator=( const API_SERVER_MANAGER& ) = delete;
 
    bool startServerProcess( const wxString& aCliPath, wxString* aError )
    {
        if( m_pid != 0 )
            return true;
 
        if( !wxFileExists( aCliPath ) )
        {
            if( aError )
                *aError = wxS( "kicad-cli path does not exist: " ) + aCliPath;
 
            return false;
        }
 
        m_stdout.clear();
        m_stderr.clear();
        m_exitCode = 0;
 
        m_process = new API_SERVER_PROCESS(
                [this]( int aStatus, const wxString& aOutput, const wxString& aErrOutput )
                {
                    m_exitCode = aStatus;
                    m_stdout += aOutput;
                    m_stderr += aErrOutput;
                    m_pid = 0;
                    m_process = nullptr;
                    m_ready = false;
                } );
 
        m_process->Redirect();
 
        std::vector<const wchar_t*> args = { aCliPath.wc_str(), wxS( "api-server" ), wxS( "--socket" ),
                                             m_socketPath.wc_str(), nullptr };
 
        m_pid = wxExecute( args.data(), wxEXEC_ASYNC, m_process );
 
        if( m_pid == 0 )
        {
            delete m_process;
            m_process = nullptr;
 
            if( aError )
                *aError = wxS( "Failed to launch kicad-cli api-server" );
 
            return false;
        }
 
        return true;
    }
 
    bool connectAndWaitReady( wxString* aError )
    {
        auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds( 15 );
 
        while( std::chrono::steady_clock::now() < deadline )
        {
            wxMilliSleep( 100 );
            collectServerOutput();
 
            if( !isProcessAlive() )
            {
                if( aError )
                    *aError = wxS( "kicad-cli process exited before ready" );
 
                return false;
            }
 
            if( !m_client.Connect( m_socketUrl ) )
            {
                wxLogTrace( traceApi, "kicad-cli connect attempt failed, will retry" );
                continue;
            }
 
            kiapi::common::ApiStatusCode pingStatus = kiapi::common::AS_UNKNOWN;
 
            if( m_client.Ping( &pingStatus ) )
            {
                if( pingStatus == kiapi::common::AS_OK )
                    return true;
 
                if( pingStatus != kiapi::common::AS_NOT_READY )
                {
                    if( aError )
                    {
                        *aError = wxString::Format( wxS( "Ping returned unexpected status: %s" ),
                                                    magic_enum::enum_name( pingStatus ) );
                    }
 
                    return false;
                }
 
                wxLogTrace( traceApi, "kicad-cli connected but returned AS_NOT_READY, will retry" );
            }
            else
            {
                wxLogTrace( traceApi, "kicad-cli ping attempt failed, will retry" );
            }
        }
 
        if( aError )
            *aError = wxS( "Timed out waiting for kicad-cli to start up" );
 
        return false;
    }
 
    void collectServerOutput()
    {
        if( !m_process )
            return;
 
        API_SERVER_PROCESS::drainStream( m_process->GetInputStream(), m_stdout );
        API_SERVER_PROCESS::drainStream( m_process->GetErrorStream(), m_stderr );
    }
 
    bool isProcessAlive() const
    {
        if( m_pid == 0 )
            return false;
 
#ifdef __UNIX__
        int   status = 0;
        pid_t result = waitpid( static_cast<pid_t>( m_pid ), &status, WNOHANG );
 
        if( result == 0 )
            return true;
 
        if( result > 0 )
        {
            if( WIFSIGNALED( status ) )
            {
                BOOST_TEST_MESSAGE( wxString::Format( "api-server killed by signal %d (%s)",
                                                      WTERMSIG( status ),
                                                      strsignal( WTERMSIG( status ) ) ) );
            }
            else if( WIFEXITED( status ) )
            {
                BOOST_TEST_MESSAGE( wxString::Format( "api-server exited with code %d",
                                                      WEXITSTATUS( status ) ) );
            }
 
            return false;
        }
#endif
 
        return wxProcess::Exists( m_pid );
    }
 
    bool                m_ready = false;
    API_TEST_CLIENT     m_client;
    API_SERVER_PROCESS* m_process = nullptr;
    long                m_pid = 0;
    wxString            m_socketPath;
    wxString            m_socketUrl;
    wxString            m_stdout;
    wxString            m_stderr;
    mutable int         m_exitCode = 0;
};
 

class API_SERVER_E2E_FIXTURE
{
public:
    API_SERVER_E2E_FIXTURE()
    {
        m_cliPath = wxString::FromUTF8( QA_KICAD_CLI_PATH );
    }
 
    ~API_SERVER_E2E_FIXTURE()
    {
        API_SERVER_MANAGER::Instance().Client().CloseAllDocuments();
    }

    bool Start( const wxString& aCliPathOverride = wxString() )
    {
        wxString cliPath = aCliPathOverride.IsEmpty() ? m_cliPath : aCliPathOverride;
 
        API_SERVER_MANAGER& manager = API_SERVER_MANAGER::Instance();
 
        if( manager.EnsureReady( cliPath, &m_lastError ) )
            return true;
 
        // First attempt failed. The server may have crashed during a previous test.
        manager.Reset();
 
        return manager.EnsureReady( cliPath, &m_lastError );
    }
 
    API_TEST_CLIENT& Client() { return API_SERVER_MANAGER::Instance().Client(); }
 
    wxString CliPath() const { return m_cliPath; }
 
    const wxString& LastError() const { return m_lastError; }
 
private:
    wxString m_cliPath;
    wxString m_lastError;
};
 
#endif // QA_API_E2E_UTILS_H